Package net.sf.saxon.s9api

## Class XdmItem

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

- All Implemented Interfaces:
    `java.lang.Iterable<XdmItem>`
  Direct Known Subclasses:
    `XdmAtomicValue`, `XdmExternalObject`, `XdmFunctionItem`, `XdmNode`

      public abstract class XdmItem
      extends XdmValue

  The class XdmItem represents an item in a sequence, as defined by the XDM data model. An item may be an atomic value, a node, a function item (including maps and arrays), or an external object.

  An item is a member of a sequence, but it can also be considered as a sequence (of length one) in its own right. `XdmItem` is a subtype of `XdmValue` because every Item in the XDM data model is also a value.

  It cannot be assumed that every sequence of length one will be represented by an `XdmItem`. It is quite possible for an `XdmValue` that is not an `XdmItem` to hold a singleton sequence.

  Saxon provides a number of concrete subclasses of `XdmItem`, namely `XdmAtomicValue`, `XdmNode`, `XdmFunctionItem` and `XdmExternalObject`. Users must not attempt to create additional subclasses.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XdmItem()` |
    `` | `XdmItem​(Item item)` | Construct an XdmItem as a wrapper around an existing Saxon Item object

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.util.Map<XdmAtomicValue,​XdmValue>` | `asMap()` | If this item is a map, return a corresponding Java Map.
    `java.lang.String` | `getStringValue()` | Get the string value of the item.
    `Item` | `getUnderlyingValue()` | Get the underlying implementation object representing the value.
    `boolean` | `isAtomicValue()` | Determine whether the item is an atomic value or some other type of item
    `boolean` | `isNode()` | Determine whether the item is a node or some other type of item
    `boolean` | `matches​(ItemType type)` | Determine whether this item matches a given item type.
    `int` | `size()` | Get the number of items in the sequence
    `XdmStream<? extends XdmItem>` | `stream()` | Get a stream comprising the items in this value
    `protected static XdmItem` | `wrapItem​(Item item)` |
    `protected static XdmNode` | `wrapItem​(NodeInfo item)` |
    `protected static XdmAtomicValue` | `wrapItem​(AtomicValue item)` |

    - ### Methods inherited from class net.sf.saxon.s9api.XdmValue

      `append, documentOrder, fromGroundedValue, isEmpty, itemAt, iterator, makeSequence, makeValue, select, setValue, toString, wrap, wrap`

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

    - #### XdmItem

          protected XdmItem()

    - #### XdmItem

          public XdmItem​(Item item)

      Construct an XdmItem as a wrapper around an existing Saxon Item object
      Parameters:
        `item` - the Item object to be wrapped. This can be retrieved using the `getUnderlyingValue()` method.
      Throws:
        `java.lang.NullPointerException` - if item is null
      Since:
        9.5 (previously a protected constructor)

  - ### Method Detail

    - #### wrapItem

          protected static XdmItem wrapItem​(Item item)

    - #### wrapItem

          protected static XdmNode wrapItem​(NodeInfo item)

    - #### wrapItem

          protected static XdmAtomicValue wrapItem​(AtomicValue item)

    - #### getUnderlyingValue

          public Item 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.
      Overrides:
        `getUnderlyingValue` in class `XdmValue`
      Returns:
        the underlying implementation object representing the value
      Since:
        9.8 (previously inherited from XdmValue which returns a Sequence)

    - #### getStringValue

          public java.lang.String getStringValue()

      Get the string value of the item. For a node, this gets the string value of the node. For an atomic value, it has the same effect as casting the value to a string. In all cases the result is the same as applying the XPath string() function.

      For atomic values, the result is the same as the result of calling `toString`. This is not the case for nodes, where `toString` returns an XML serialization of the node.

      Returns:
        the result of converting the item to a string.

    - #### isNode

          public boolean isNode()

      Determine whether the item is a node or some other type of item
      Returns:
        true if the item is a node, false if it is an atomic value or a function (including maps and arrays)
      Since:
        10.0

    - #### isAtomicValue

          public boolean isAtomicValue()

      Determine whether the item is an atomic value or some other type of item
      Returns:
        true if the item is an atomic value, false if it is a node or a function (including maps and arrays)

    - #### size

          public int size()

      Get the number of items in the sequence
      Overrides:
        `size` in class `XdmValue`
      Returns:
        the number of items in the value. For an item (including a map or array) this is always 1 (one).

    - #### asMap

          public java.util.Map<XdmAtomicValue,​XdmValue> asMap()

      If this item is a map, return a corresponding Java Map.
      Returns:
        if this item is a map, return a mutable Map from atomic values to (sequence) values, containing the same entries as this map. Otherwise return null.
      Since:
        9.6.

    - #### stream

          public XdmStream<? extends XdmItem> stream()

      Get a stream comprising the items in this value
      Overrides:
        `stream` in class `XdmValue`
      Returns:
        a Stream over the items in this value
      Since:
        9.9

    - #### matches

          public boolean matches​(ItemType type)

      Determine whether this item matches a given item type.
      Parameters:
        `type` - the item type to be tested against this item
      Returns:
        true if the item matches this item type, false if it does not match.
      Since:
        9.9