net.sf.saxon.s9api

## Class XdmItem

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

- All Implemented Interfaces:
    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 is either an atomic value or a node.

  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 two concrete subclasses of `XdmItem`, namely `XdmNode` and `XdmAtomicValue`. Users must not attempt to create additional subclasses.

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getStringValue()` Get the string value of the item.
    `boolean` | `isAtomicValue()` Determine whether the item is an atomic value or a node
    `static XdmItem` | `newAtomicValue(String value, ItemType type)` Deprecated. since 9.1. This factory method duplicates the constructor `XdmAtomicValue.XdmAtomicValue(String, ItemType)` which should be used in preference
    `int` | `size()` Get the number of items in the sequence
    `protected static XdmItem` | `wrapItem(Item item)`

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

      `append, getUnderlyingValue, itemAt, iterator, setValue, wrap`

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

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

- - ### 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 `XdmValue.getUnderlyingValue()` method.
      Throws:
        `NullPointerException` - if item is null
      Since:
        9.5 (previously a protected constructor)

  - ### Method Detail

    - #### wrapItem

          protected static XdmItem wrapItem(Item item)

    - #### newAtomicValue

          public static XdmItem newAtomicValue(String value,
                               ItemType type)
                                        throws SaxonApiException

      Deprecated. since 9.1. This factory method duplicates the constructor `XdmAtomicValue.XdmAtomicValue(String, ItemType)` which should be used in preference
      Factory method to construct an atomic value given its lexical representation and the required item type
      Parameters:
        `value` - the lexical representation of the required value
        `type` - the item type of the required value
      Returns:
        the constructed item
      Throws:
        `SaxonApiException` - if the supplied string is not in the lexical space of the target type, or if the target type is not atomic

    - #### getStringValue

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

    - #### isAtomicValue

          public boolean isAtomicValue()

      Determine whether the item is an atomic value or a node
      Returns:
        true if the item is an atomic value, false if it is a node

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

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