Package net.sf.saxon.ma.arrays

Class ArrayItem

  • All Implemented Interfaces:
    Callable, FunctionItem, GroundedValue, Item, Sequence
    Direct Known Subclasses:
    AbstractArrayItem
    public abstract class ArrayItem
extends java.lang.Object
implements FunctionItem
    Interface supported by different implementations of an XDM array item.

    Saxon uses two main implementations of this interface: SimpleArrayItem, which is a wrapper over a Java List (which is assumed immutable), and ImmutableArrayItem, which is a wrapper over a Saxon ZenoChain, permitting efficient append and prepend operations without copying the entire content. Many of the expressions and functions that create arrays use a learning strategy to decide which implementation to use: if a significant number of SimpleArrayItem instances are subsequently converted to an ImmutableArrayItem, then future evaluations of the same expression will produce an ImmutableArrayItem directly.

    • Constructor Detail

      • ArrayItem

        public ArrayItem()

    • Method Detail

      • isArray

        public final boolean isArray()
        Ask whether this function item is an array
        Specified by:
        isArray in interface FunctionItem
        Returns:
        true if this function item is an array, otherwise false

      • isMap

        public final boolean isMap()
        Ask whether this function item is a map
        Specified by:
        isMap in interface FunctionItem
        Returns:
        false (it is not a map)

      • get

        public abstract GroundedValue get​(int index)
        Get a member of the array
        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 abstract ArrayItem put​(int index,
                              GroundedValue newValue)
        Replace a member of the array
        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

      • isEmpty

        public boolean isEmpty()
        Ask whether the array is empty
        Returns:
        true if and only if the size of the array is zero

      • members

        public abstract java.lang.Iterable<GroundedValue> members()
        Get the list of all members of the array
        Returns:
        an iterator over the members of the array

      • parcels

        public SequenceIterator parcels()
        Get an iterator over the members of the array, each represented as a Parcel
        Returns:
        an SequenceIterator over the members of the array, represented as parcels

      • append

        public abstract ArrayItem append​(GroundedValue newMember)
        Add a member to this array
        Parameters:
        newMember - the member to be added
        Returns:
        the new array, comprising the members of this array and then one additional member.

      • concat

        public abstract ArrayItem concat​(ArrayItem other)
        Concatenate this array with another
        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

      • remove

        public abstract ArrayItem remove​(int index)
        Remove a member from the array
        Parameters:
        index - the position of the member to be removed (zero-based)
        Returns:
        a new array in which the requested member has been removed.
        Throws:
        java.lang.IndexOutOfBoundsException - if index is out of range

      • removeSeveral

        public abstract ArrayItem removeSeveral​(IntSet positions)
        Remove zero or more members from the array
        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
        Throws:
        java.lang.IndexOutOfBoundsException - if any of the positions is out of range

      • subArray

        public abstract ArrayItem subArray​(int start,
                                   int end)
        Get a sub-array given a start and end position
        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 abstract ArrayItem insert​(int position,
                                 GroundedValue member)
        Insert a new member into an array
        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

      • getMemberType

        public abstract SequenceType getMemberType​(TypeHierarchy th)
        Get the lowest common item type of the members of the array
        Parameters:
        th - the type hierarchy
        Returns:
        the most specific type to which all the members belong.

      • 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 FunctionItem
        Specified by:
        toShortString in interface GroundedValue
        Specified by:
        toShortString in interface Item
        Returns:
        a depiction of the item suitable for use in error messages