Package net.sf.saxon.ma.parray

## Class ImmList<E>

- java.lang.Object
- - net.sf.saxon.ma.parray.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