Package net.sf.saxon.s9api

## Class XdmArray

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

- All Implemented Interfaces:
    `java.lang.Iterable<XdmItem>`

      public class XdmArray
      extends XdmFunctionItem

  An array in the XDM data model. An array is a list of zero or more members, each of which is an arbitrary XDM value. The array itself is an XDM item.

  An XdmArray is immutable.

  Since:
    9.8

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XdmArray()` | Create an empty XdmArray
    `XdmArray​(java.lang.Iterable<? extends XdmValue> members)` | Create an XdmArray supplying the members as a collection of XdmValue objects
    `XdmArray​(ArrayItem array)` | Create an XdmArray that wraps a supplied ArrayItem
    `XdmArray​(XdmValue[] members)` | Create an XdmArray supplying the members as an array of XdmValue objects

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `XdmArray` | `addMember​(XdmValue value)` | Append a new member to an array
    `int` | `arrayLength()` | Get the number of members in the array
    `java.util.List<XdmValue>` | `asList()` | Get the members of the array in the form of a list.
    `XdmArray` | `concat​(XdmArray value)` | Concatenate another array
    `XdmValue` | `get​(int n)` | Get the n'th member in the array, counting from zero.
    `ArrayItem` | `getUnderlyingValue()` | Get the underlying implementation object representing the value.
    `static XdmArray` | `makeArray​(boolean[] input)` | Make an XdmArray whose members are xs:boolean values
    `static XdmArray` | `makeArray​(byte[] input)` | Make an XdmArray whose members are xs:integer values
    `static XdmArray` | `makeArray​(int[] input)` | Make an XdmArray whose members are xs:integer values
    `static XdmArray` | `makeArray​(long[] input)` | Make an XdmArray whose members are xs:long values
    `static XdmArray` | `makeArray​(short[] input)` | Make an XdmArray whose members are xs:integer values
    `static XdmArray` | `makeArray​(java.lang.Object[] input)` | Make an XDM array from a Java array.
    `XdmArray` | `put​(int n, XdmValue value)` | Create a new array in which one member is replaced with a new value.

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

      `asFunction, asStep, call, getArity, getName, getSystemFunction, isAtomicValue`

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

      `asMap, getStringValue, isNode, matches, size, stream, wrapItem, wrapItem, wrapItem`

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

    - #### XdmArray

          public XdmArray()

      Create an empty XdmArray

    - #### XdmArray

          public XdmArray​(ArrayItem array)

      Create an XdmArray that wraps a supplied ArrayItem
      Parameters:
        `array` - the ArrayItem to be encapsulated

    - #### XdmArray

          public XdmArray​(XdmValue[] members)

      Create an XdmArray supplying the members as an array of XdmValue objects
      Parameters:
        `members` - an array of XdmValue objects. Note that subsequent changes to the array will have no effect on the XdmValue.

    - #### XdmArray

          public XdmArray​(java.lang.Iterable<? extends XdmValue> members)

      Create an XdmArray supplying the members as a collection of XdmValue objects
      Parameters:
        `members` - a sequence of XdmValue 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. Note that the argument can be a single XdmValue representing a sequence, in which case the constructed array will have one member for each item in the supplied sequence.

  - ### Method Detail

    - #### arrayLength

          public int arrayLength()

      Get the number of members in the array
      Returns:
        the number of members in the array. (Note that the `XdmItem.size()` method returns 1 (one), because an XDM array is an item.)

    - #### get

          public XdmValue get​(int n)
                       throws java.lang.IndexOutOfBoundsException

      Get the n'th member in the array, counting from zero.
      Parameters:
        `n` - the member that is required, counting the first member in the array as member zero
      Returns:
        the n'th member in the sequence making up the array, counting from zero
      Throws:
        `java.lang.IndexOutOfBoundsException` - if n is less than zero or greater than or equal to the number of members in the array

    - #### put

          public XdmArray put​(int n,
                              XdmValue value)
                       throws java.lang.IndexOutOfBoundsException

      Create a new array in which one member is replaced with a new value.
      Parameters:
        `n` - the position of the member that is to be replaced, counting the first member in the array as member zero
        `value` - the new value for this member
      Returns:
        a new array, the same length as the original, with one member replaced by a new value
      Throws:
        `java.lang.IndexOutOfBoundsException` - if n is less than zero or greater than or equal to the number of members in the array

    - #### addMember

          public XdmArray addMember​(XdmValue value)

      Append a new member to an array
      Parameters:
        `value` - the new member
      Returns:
        a new array, one item longer than the original
      Throws:
        `SaxonApiUncheckedException` - if the value is lazily evaluated, and evaluation fails
      Since:
        9.9. (See bug 3968: on first release of 9.9, the method was mistakenly named `append`).

    - #### concat

          public XdmArray concat​(XdmArray value)

      Concatenate another array
      Parameters:
        `value` - the other array
      Returns:
        a new array, containing the members of this array followed by the members of the other array
      Since:
        9.9

    - #### asList

          public java.util.List<XdmValue> asList()

      Get the members of the array in the form of a list.
      Returns:
        a list of the members of this array.

    - #### getUnderlyingValue

          public ArrayItem 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 `XdmItem`
      Returns:
        the underlying implementation object representing the value

    - #### makeArray

          public static XdmArray makeArray​(java.lang.Object[] input)
                                    throws java.lang.IllegalArgumentException

      Make an XDM array from a Java array. Each member of the supplied array is converted to a single member in the result array using the method `XdmValue.makeValue(Object)`
      Returns:
        the result of the conversion if successful
      Throws:
        `java.lang.IllegalArgumentException` - if conversion is not possible

    - #### makeArray

          public static XdmArray makeArray​(boolean[] input)

      Make an XdmArray whose members are xs:boolean values
      Parameters:
        `input` - the input array of booleans
      Returns:
        an XdmArray whose members are xs:boolean values corresponding one-to-one with the input

    - #### makeArray

          public static XdmArray makeArray​(long[] input)

      Make an XdmArray whose members are xs:long values
      Parameters:
        `input` - the input array of integers
      Returns:
        an XdmArray whose members are xs:integer values corresponding one-to-one with the input

    - #### makeArray

          public static XdmArray makeArray​(int[] input)

      Make an XdmArray whose members are xs:integer values
      Parameters:
        `input` - the input array of integers
      Returns:
        an XdmArray whose members are xs:integer values corresponding one-to-one with the input

    - #### makeArray

          public static XdmArray makeArray​(short[] input)

      Make an XdmArray whose members are xs:integer values
      Parameters:
        `input` - the input array of integers
      Returns:
        an XdmArray whose members are xs:integer values corresponding one-to-one with the input

    - #### makeArray

          public static XdmArray makeArray​(byte[] input)

      Make an XdmArray whose members are xs:integer values
      Parameters:
        `input` - the input array of integers
      Returns:
        an XdmArray whose members are xs:integer values corresponding one-to-one with the input