Package net.sf.saxon.ma.arrays

## Class SimpleArrayItem

- java.lang.Object
- - net.sf.saxon.ma.arrays.AbstractArrayItem
  - - net.sf.saxon.ma.arrays.SimpleArrayItem

- All Implemented Interfaces:
    `Callable`, `ArrayItem`, `Function`, `GroundedValue`, `Item`, `Sequence`

      public class SimpleArrayItem
      extends AbstractArrayItem
      implements ArrayItem

  A simple implementation of XDM array items, in which the array is backed by a Java List.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static SimpleArrayItem` | `EMPTY_ARRAY` | Static constant value representing an empty array

    - ### Fields inherited from interface net.sf.saxon.ma.arrays.ArrayItem

      `SINGLE_ARRAY_TYPE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SimpleArrayItem​(java.util.List<GroundedValue> members)` | Construct an array whose members are arbitrary sequences

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `arrayLength()` | Get the size of the array
    `ArrayItem` | `concat​(ArrayItem other)` | Concatenate this array with another
    `GroundedValue` | `get​(int index)` | Get a member of the array
    `AnnotationList` | `getAnnotations()` | Get the function annotations (as defined in XQuery).
    `java.util.List<GroundedValue>` | `getMembers()` | Get a list of the members of the array
    `OperandRole[]` | `getOperandRoles()` | Get the roles of the arguments, for the purposes of streaming
    `ArrayItem` | `insert​(int position, GroundedValue member)` | Insert a new member into an array
    `boolean` | `isArray()` | Ask whether this function item is an array
    `boolean` | `isEmpty()` | Ask whether the array is empty
    `boolean` | `isMap()` | Ask whether this function item is a map
    `void` | `makeGrounded()` | Ensure that all the members are grounded.
    `static SimpleArrayItem` | `makeSimpleArrayItem​(SequenceIterator input)` | Construct an array whose members are single items
    `java.lang.Iterable<GroundedValue>` | `members()` | Get the list of all members of the array
    `ArrayItem` | `put​(int index, GroundedValue newValue)` | Replace a member of the array
    `ArrayItem` | `remove​(int pos)` | Remove a member from the array
    `ArrayItem` | `removeSeveral​(IntSet positions)` | Remove zero or more members from the array
    `ArrayItem` | `subArray​(int start, int end)` | Get a subarray given a start and end position
    `java.lang.String` | `toShortString()` | Provide a short string showing the contents of the item, suitable for use in error messages

    - ### Methods inherited from class net.sf.saxon.ma.arrays.AbstractArrayItem

      `atomize, call, deepEquals, effectiveBooleanValue, export, getArity, getDescription, getFunctionItemType, getFunctionName, getMemberType, getStringValue, getStringValueCS, isTrustedResultType, makeNewContext, toString`

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

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

    - ### Methods inherited from interface net.sf.saxon.ma.arrays.ArrayItem

      `getGenre, getMemberType`

    - ### Methods inherited from interface net.sf.saxon.om.Function

      `call, deepEquals, export, getArity, getDescription, getFunctionItemType, getFunctionName, isTrustedResultType, makeNewContext`

    - ### Methods inherited from interface net.sf.saxon.om.GroundedValue

      `asIterable, concatenate, containsNode, effectiveBooleanValue, materialize`

    - ### Methods inherited from interface net.sf.saxon.om.Item

      `atomize, getLength, getStringValue, getStringValueCS, head, isStreamed, itemAt, iterate, reduce, subsequence`

    - ### Methods inherited from interface net.sf.saxon.om.Sequence

      `makeRepeatable`

- - ### Field Detail

    - #### EMPTY_ARRAY

          public static final SimpleArrayItem EMPTY_ARRAY

      Static constant value representing an empty array

  - ### Constructor Detail

    - #### SimpleArrayItem

          public SimpleArrayItem​(java.util.List<GroundedValue> members)

      Construct an array whose members are arbitrary sequences
      Parameters:
        `members` - the list of values (in general, each value is a sequence) to form the members of the array. The values must be repeatable sequences (not LazySequences); this is not checked.

  - ### Method Detail

    - #### makeSimpleArrayItem

          public static SimpleArrayItem makeSimpleArrayItem​(SequenceIterator input)
                                                     throws XPathException

      Construct an array whose members are single items
      Parameters:
        `input` - an iterator over the items to make up the array
      Returns:
        an array in which each member is a single item, taken from the input sequence
      Throws:
        `XPathException` - if evaluating the SequenceIterator fails

    - #### getOperandRoles

          public OperandRole[] getOperandRoles()

      Get the roles of the arguments, for the purposes of streaming
      Specified by:
        `getOperandRoles` in interface `Function`
      Overrides:
        `getOperandRoles` in class `AbstractArrayItem`
      Returns:
        an array of OperandRole objects, one for each argument

    - #### makeGrounded

          public void makeGrounded()
                            throws XPathException

      Ensure that all the members are grounded. The idea is that a member may initially be a reference to a lazily-evaluated sequence, but once computed, the reference will be replaced with the actual value
      Throws:
        `XPathException`

    - #### isArray

          public boolean isArray()

      Ask whether this function item is an array
      Specified by:
        `isArray` in interface `Function`
      Overrides:
        `isArray` in class `AbstractArrayItem`
      Returns:
        true (it is an array)

    - #### isMap

          public boolean isMap()

      Ask whether this function item is a map
      Specified by:
        `isMap` in interface `Function`
      Overrides:
        `isMap` in class `AbstractArrayItem`
      Returns:
        false (it is not a map)

    - #### getAnnotations

          public AnnotationList getAnnotations()

      Get the function annotations (as defined in XQuery). Returns an empty list if there are no function annotations.
      Specified by:
        `getAnnotations` in interface `Function`
      Overrides:
        `getAnnotations` in class `AbstractArrayItem`
      Returns:
        the function annotations

    - #### get

          public GroundedValue get​(int index)

      Get a member of the array
      Specified by:
        `get` in interface `ArrayItem`
      Parameters:
        `index` - the position of the member to retrieve (zero-based)
      Returns:
        the value at the given position.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### put

          public ArrayItem put​(int index,
                               GroundedValue newValue)

      Replace a member of the array
      Specified by:
        `put` in interface `ArrayItem`
      Parameters:
        `index` - the position of the member to replace (zero-based)
        `newValue` - the replacement value
      Returns:
        the value at the given position.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### arrayLength

          public int arrayLength()

      Get the size of the array
      Specified by:
        `arrayLength` in interface `ArrayItem`
      Returns:
        the number of members in this array

    - #### isEmpty

          public boolean isEmpty()

      Ask whether the array is empty
      Specified by:
        `isEmpty` in interface `ArrayItem`
      Returns:
        true if and only if the size of the array is zero

    - #### members

          public java.lang.Iterable<GroundedValue> members()

      Get the list of all members of the array
      Specified by:
        `members` in interface `ArrayItem`
      Returns:
        an iterator over the members of the array

    - #### removeSeveral

          public ArrayItem removeSeveral​(IntSet positions)

      Remove zero or more members from the array
      Specified by:
        `removeSeveral` in interface `ArrayItem`
      Parameters:
        `positions` - the positions of the members to be removed (zero-based). A value that is out of range is ignored.
      Returns:
        a new array in which the requested member has been removed

    - #### remove

          public ArrayItem remove​(int pos)

      Remove a member from the array
      Specified by:
        `remove` in interface `ArrayItem`
      Parameters:
        `pos` - the position of the member to be removed (zero-based). A value that is out of range results in an IndexOutOfBoundsException
      Returns:
        a new array in which the requested member has been removed

    - #### subArray

          public ArrayItem subArray​(int start,
                                    int end)

      Get a subarray given a start and end position
      Specified by:
        `subArray` in interface `ArrayItem`
      Parameters:
        `start` - the start position (zero based)
        `end` - the end position (the position of the first item not to be returned) (zero based)
      Returns:
        a new array item containing the sub-array
      Throws:
        `java.lang.IndexOutOfBoundsException` - if start, or start+end, is out of range

    - #### insert

          public ArrayItem insert​(int position,
                                  GroundedValue member)

      Insert a new member into an array
      Specified by:
        `insert` in interface `ArrayItem`
      Parameters:
        `position` - the 0-based position that the new item will assume
        `member` - the new member to be inserted
      Returns:
        a new array item with the new member inserted
      Throws:
        `java.lang.IndexOutOfBoundsException` - if position is out of range

    - #### concat

          public ArrayItem concat​(ArrayItem other)

      Concatenate this array with another
      Specified by:
        `concat` in interface `ArrayItem`
      Parameters:
        `other` - the second array
      Returns:
        the concatenation of the two arrays; that is, an array containing first the members of this array, and then the members of the other array

    - #### getMembers

          public java.util.List<GroundedValue> getMembers()

      Get a list of the members of the array
      Returns:
        the list of members. Note that this returns the actual contained member array, and this is mutable. Changes to this array are permitted only if the caller knows what they are doing, for example during initial construction of an array that will not be presented to the user until construction has finished.

    - #### toShortString

          public java.lang.String toShortString()

      Provide a short string showing the contents of the item, suitable for use in error messages
      Specified by:
        `toShortString` in interface `ArrayItem`
      Specified by:
        `toShortString` in interface `Function`
      Specified by:
        `toShortString` in interface `GroundedValue`
      Specified by:
        `toShortString` in interface `Item`
      Returns:
        a depiction of the item suitable for use in error messages