Package net.sf.saxon.ma.parray

Class ImmList<E>

  • Type Parameters:
    E - the type of the elements in the list
    All Implemented Interfaces:
    java.lang.Iterable<E>
    Direct Known Subclasses:
    ImmList0, ImmList1, ImmList2
    public abstract class ImmList<E>
extends java.lang.Object
implements java.lang.Iterable<E>
    An immutable list of elements

    • Constructor Summary

      Constructors 
      Constructor Description
      ImmList()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract ImmList<E> append​(E member)
      Append an element at the end of the list
      abstract ImmList<E> appendList​(ImmList<E> members)
      Append multiple elements at the end of the list
      static <E> ImmList<E> empty()
      Return an empty list
      static <E> ImmList<E> fromList​(java.util.List<E> members)
      Construct an immutable list from a Java list of members
      abstract E get​(int index)
      Get the element at a given index
      E head()
      Get the first element in the list
      abstract ImmList<E> insert​(int index, E member)
      Insert an element at a given position
      abstract boolean isEmpty()
      Ask if the list is empty
      protected java.lang.IndexOutOfBoundsException outOfBounds​(int requested, int actual)
      Convenience method for use by subclasses to throw an IndexOutOfBounds exception when needed
      static <E> ImmList<E> pair​(E first, E second)
      Return a list of length 2 (two)
      protected ImmList<E> rebalance()
      Return a list containing the same elements as this list, but optimized for efficient access
      abstract ImmList<E> remove​(int index)
      Remove the member at a given position
      abstract ImmList<E> replace​(int index, E member)
      Replace the element at a given index
      static <E> ImmList<E> singleton​(E member)
      Return a singleton list (a list containing one item)
      abstract int size()
      Get the size of the list
      abstract ImmList<E> subList​(int start, int end)
      Return a sub-sequence with a given start and end position
      ImmList<E> tail()
      Get a list containing all elements of the list except the first

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, iterator, spliterator

    • Constructor Detail

      • ImmList

        public ImmList()

    • Method Detail

      • empty

        public static <E> ImmList<E> empty()
        Return an empty list
        Type Parameters:
        E - the (nominal) type of the list element
        Returns:
        an empty immutable list

      • singleton

        public static <E> ImmList<E> singleton​(E member)
        Return a singleton list (a list containing one item)
        Type Parameters:
        E - the type of the list members
        Parameters:
        member - the single member of the list
        Returns:
        the singleton list

      • pair

        public static <E> ImmList<E> pair​(E first,
                                  E second)
        Return a list of length 2 (two)
        Type Parameters:
        E - the type of the list members
        Parameters:
        first - the first member of the list
        second - the second member of the list
        Returns:
        the two-member list

      • fromList

        public static <E> ImmList<E> fromList​(java.util.List<E> members)
        Construct an immutable list from a Java list of members
        Type Parameters:
        E - the type of the list members
        Parameters:
        members - the members to be added to the list
        Returns:
        the immutable list

      • get

        public abstract E get​(int index)
        Get the element at a given index
        Parameters:
        index - the required index (zero-based)
        Returns:
        the element at the given index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range

      • head

        public E head()
        Get the first element in the list
        Returns:
        the result of get(0)
        Throws:
        java.lang.IndexOutOfBoundsException - if the list is empty

      • size

        public abstract int size()
        Get the size of the list
        Returns:
        the number of members in the list

      • isEmpty

        public abstract boolean isEmpty()
        Ask if the list is empty
        Returns:
        true if the list contains no elements, otherwise false

      • replace

        public abstract ImmList<E> replace​(int index,
                                   E member)
        Replace the element at a given index
        Parameters:
        index - the index (zero-based) of the element to be replaced
        member - the replacement member to be included in the new list
        Returns:
        a new list, identical to the old except for the replacement of one member
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range

      • insert

        public abstract ImmList<E> insert​(int index,
                                  E member)
        Insert an element at a given position
        Parameters:
        index - the position (zero-based) for the insertion. The new element will be inserted before the existing element at this position. If the index is equal to the list size, the new element is inserted at the end.
        member - the new member to be included in the new list
        Returns:
        a new list, identical to the old except for the addition of one member
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range

      • append

        public abstract ImmList<E> append​(E member)
        Append an element at the end of the list
        Parameters:
        member - the new member to be included in the new list
        Returns:
        a new list, identical to the old except for the addition of one member

      • appendList

        public abstract ImmList<E> appendList​(ImmList<E> members)
        Append multiple elements at the end of the list
        Parameters:
        members - the new members to be included in the new list
        Returns:
        a new list, identical to the old except for the addition of new members

      • remove

        public abstract ImmList<E> remove​(int index)
        Remove the member at a given position
        Parameters:
        index - the zero-based index position of the member to be removed
        Returns:
        a new list, identical to the old except for the removal of one member
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range

      • subList

        public abstract ImmList<E> subList​(int start,
                                   int end)
        Return a sub-sequence with a given start and end position
        Parameters:
        start - the zero-based index position of the first member to be extracted
        end - the zero-based index position of the first member after the sub-sequence to be extracted
        Returns:
        a new list containing the elements from the specified range of positions
        Throws:
        java.lang.IndexOutOfBoundsException - if either index is out of range or if end precedes start

      • tail

        public ImmList<E> tail()
        Get a list containing all elements of the list except the first
        Returns:
        the result of subList(1, size()), or equivalently remove(0)
        Throws:
        java.lang.IndexOutOfBoundsException - if the list is empty

      • rebalance

        protected ImmList<E> rebalance()
        Return a list containing the same elements as this list, but optimized for efficient access
        Returns:
        either this list, or a copy containing the same elements in the same order

      • outOfBounds

        protected java.lang.IndexOutOfBoundsException outOfBounds​(int requested,
                                                          int actual)
        Convenience method for use by subclasses to throw an IndexOutOfBounds exception when needed
        Parameters:
        requested - the index value that was requested by the caller
        actual - the actual size of the list
        Returns:
        an IndexOutOfBoundsException with suitable message text