Package eu.simuline.util

Class TwoSidedList<E>

  • Type Parameters:
    E - the class of the elements of this list. Created: Sun Aug 26 23:25:26 2007
    All Implemented Interfaces:
    java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>
    public final class TwoSidedList<E>
extends java.lang.Object
implements java.util.List<E>
    Compared to a classical list, the first index of this list may well be positive and negative indices are allowed as well.

    As a consequence, one can add elements not only at the end of this list but also at its beginning. For details consider add(Object), addFirst(Object) and addLast(Object). Method add(int ind, Object obj) is not supported because inserting an element requires either shift of subsequent elements to the right or preceeding elements to the left. To determine the direction of the shift use add(int ind, Object obj, Direction dir) instead. Similar considerations apply to methods removing elements. Also affected are the corresponding collections operations like addAll.

    Methods toArray() and toArray(Object[]) satisfy a generalized contract based on the additional method firstIndex().

    Essentially this two sided list wrapps a classical list. Various constructors allow to pass that list. This allows to determine the performance behavior. The signatures of the constructors generalize the constructors known from implementations of classical Lists. The observant reader observes that the generics are slightly more restrictive than for classical lists. This is for performance reasons. Note that the constructors do not create a copy of the wrapped list which may cause hidden dependencies. If full generality is needed the user is asked to use the corresponding factory methods.

    Additionally methods concerning indices are provided like firstIndex(), minFreeIndex() and it is possible to shift a list using shiftRight(int).

    Version:
    1.0
    Author:
    Ernst Reissner

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  TwoSidedList.Direction
      Used as an argument for methods adding or removing elements from this list to determine in which direction this list has to shrink or grow.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int firstIndex
      The first index in this TwoSidedList.
      private java.util.List<E> list
      The list backed by this two-sided list.

    • Constructor Summary

      Constructors 
      Constructor Description
      TwoSidedList​(int firstIndex)
      Creates a new empty TwoSidedList which starts growing with index firstIndex.
      TwoSidedList​(TwoSidedList<E> other)
      Copy constructor with shallow copy of the wrapped list list.
      TwoSidedList​(java.util.List<E> list)
      Creates a new TwoSidedList from a List with firstIndex == 0.
      TwoSidedList​(java.util.List<E> list, int firstIndex)
      Creates a new TwoSidedList containing the elements of list in proper sequence with first index given by firstIndex.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(int ind, E obj)
      Not supported by this implementation. **** breaks contract
      void add​(int ind, E obj, TwoSidedList.Direction dir)
      Inserts obj at the specified position ind in this list (optional operation).
      boolean add​(E obj)
      Not supported by this implementation. **** breaks contract
      boolean addAll​(int ind, java.util.Collection<? extends E> coll)
      Not supported by this implementation.
      boolean addAll​(int ind, java.util.Collection<? extends E> coll, TwoSidedList.Direction dir)
      Inserts all of the elements in coll into this list at the specified position (optional operation).
      boolean addAll​(java.util.Collection<? extends E> coll)
      Not supported by this implementation.
      boolean addAllFirst​(java.util.Collection<? extends E> coll)
      Adds obj at the beginning of this list.
      boolean addAllLast​(java.util.Collection<? extends E> coll)
      Appends all of the elements in coll to the end of this list, in the order that they are returned by coll's iterator (optional operation).
      boolean addFirst​(E obj)
      Adds obj at the beginning of this list.
      boolean addLast​(E obj)
      Adds obj at the end of this list.
      (package private) void checkIncMinFreeIndex()
      Checks whether incrementing minFreeIndex() would cause overrun of minFreeIndex().
      (package private) void checkMinFreeIndex​(int numAdded)
      Checks whether adding numAdded objects to this list **** or at the tail of this list would cause overrun of minFreeIndex().
      (package private) void checkRange​(int ind)
      Checks whether index ind is in range and throws an appropriate exception if not.
      private void checkRange​(int ind, TwoSidedList.Direction dir)
      Checks whether index ind is in range and throws an appropriate exception if not.
      private void checkRange​(java.lang.String fromToNothing, int ind, int min, int maxP)
      Checks whether index ind is in range and throws an appropriate exception if not.
      void clear()
      Removes all of the elements from this list (optional operation).
      boolean contains​(java.lang.Object obj)
      Returns whether this list contains the specified element.
      boolean containsAll​(java.util.Collection<?> coll)
      Replaces the element at the indth position in this list with the specified element (optional operation).
      static <E> TwoSidedList<E> create​(TwoSidedList<? extends E> other)
      Creates a new TwoSidedList as a copy of other copying also the wrapped list list.
      static <E> TwoSidedList<E> create​(java.util.List<? extends E> list)
      Creates a new TwoSidedList containing the elements of list in proper sequence.
      static <E> TwoSidedList<E> create​(java.util.List<? extends E> list, int firstIndex)
      Creates a new TwoSidedList containing the elements of list in proper sequence with first index given by firstIndex.
      private void decFirstIndex()
      Decrements firstIndex if possible; otherwise throws an exception.
      boolean equals​(java.lang.Object obj)
      The given object equals this twosided list if and only if it is as well a TwoSidedList, the two lists wrapped list coincide and either as well the first indices firstIndex coincide.
      int firstIndex()
      Returns firstIndex.
      void firstIndex​(int firstIndex)
      Sets firstIndex according to the parameter.
      E get​(int ind)
      Returns the element at the specified position in this list.
      int hashCode()
      Returns a hash code which conforms with equals(Object).
      private void incFirstIndex()
      Increments firstIndex if possible; otherwise throws an exception.
      int indexOf​(java.lang.Object obj)
      Returns the index of the first occurrence of the specified element obj in this list, or firstIndex()-1 if this list does not contain the element.
      boolean isEmpty()
      Returns true if this list contains no elements.
      java.util.Iterator<E> iterator()  
      int lastIndexOf​(java.lang.Object obj)
      Returns the index of the last occurrence of the specified element obj in this list, or firstIndex()-1 if this list does not contain the element.
      java.util.List<E> list()  
      java.util.ListIterator<E> listIterator()  
      java.util.ListIterator<E> listIterator​(int ind)
      ****maybe to be endowed with a direction.
      static void main​(java.lang.String[] args)  
      int minFreeIndex()  
      E remove​(int ind)
      Not supported by this implementation. **** breaks contract
      E remove​(int ind, TwoSidedList.Direction dir)
      Removes the element at the specified position in this list (optional operation).
      boolean remove​(java.lang.Object obj)
      Not supported by this implementation. **** breaks contract
      boolean removeAll​(java.util.Collection<?> coll)
      Not supported by this implementation.
      boolean removeAll​(java.util.Collection<?> coll, TwoSidedList.Direction dir)
      Removes from this list all of its elements that are contained in coll (optional operation).
      boolean removeFirst​(java.lang.Object obj)
      Removes the first occurrence of obj from this list, if present (optional operation).
      boolean removeLast​(java.lang.Object obj)
      Removes the last occurrence of obj from this list, if present (optional operation).
      boolean retainAll​(java.util.Collection<?> coll)
      Not supported by this implementation.
      boolean retainAll​(java.util.Collection<?> coll, TwoSidedList.Direction dir)
      Retains only the elements in this list that are contained in coll (optional operation).
      E set​(int ind, E obj)
      Replaces the element at the indth position in this list with the specified element (optional operation).
      int shiftRight​(int num)
      Shifts this list num indices to the right.
      int size()
      Returns the number of elements in this list.
      private void subFirstIndex​(int numAdded)
      Subtracts numAdded from firstIndex if possible; otherwise throws an exception.
      java.util.List<E> subList​(int indStart, int indEnd)
      Returns a view of the portion of this twosided list as a list between the specified fromIndex, inclusive, and toIndex, exclusive.
      TwoSidedList<E> subList2​(int indStart, int indEnd)
      Returns a view of the portion of this twosided list between the specified fromIndex, inclusive, and toIndex, exclusive.
      java.lang.Object[] toArray()
      Note that this generalizes the contract of the underlying interface: Instead of this.toArray[i] == this.get(i) now only this.toArray[i] == this.get(i-firstIndex()).
      <E> E[] toArray​(E[] objArr)
      Note that this generalizes the contract of the underlying interface: Instead of this.toArray[i] == this.get(i) now only this.toArray[i] == this.get(i-firstIndex()).
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Collection

        parallelStream, removeIf, stream, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

      • Methods inherited from interface java.util.List

        replaceAll, sort, spliterator

    • Field Detail

      • list

        private java.util.List<E> list
        The list backed by this two-sided list.

      • firstIndex

        private int firstIndex
        The first index in this TwoSidedList. Note that this integer may well be negative. The inequality minFreeIndex() >= firstIndex is guaranteed. Casually, methods adding objects have to reject them in order not to hurt this alhough the backed list list would allow adding further elements.

    • Constructor Detail

      • TwoSidedList

        public TwoSidedList​(java.util.List<E> list,
                    int firstIndex)
        Creates a new TwoSidedList containing the elements of list in proper sequence with first index given by firstIndex.

        Note the difference to reference implementations such as java.util.ArrayList where the type of the list argument is List<? extends E>. We deviate from this solution for performance reason and provide as an alternative the factory method create(List,int).

        CAUTION: This list backs list and so changes to one of the list affect the other list.

        Parameters:
        list - the list wrapped by this twosided list.
        firstIndex - the index where this list starts growing.
        Throws:
        java.lang.IllegalStateException - if list is so long and firstIndex is so large that minFreeIndex() would overrun.

      • TwoSidedList

        public TwoSidedList​(java.util.List<E> list)
        Creates a new TwoSidedList from a List with firstIndex == 0. This is the canonical generalization of lists as mentioned in the documentation of indexOf(Object) and of lastIndexOf(Object).

        Note the difference to reference implementations such as java.util.ArrayList where the type of the list argument is List<? extends E>. We deviate from this solution for performance reason and provide as an alternative the factory method create(List,int).

        CAUTION: Changes to list influence this twosided list and may cause malfunction. Note that unlike TwoSidedList(List, int) this constructor cannot throw an IllegalStateException.

        Parameters:
        list - the list wrapped by this twosided list.

      • TwoSidedList

        public TwoSidedList​(TwoSidedList<E> other)
        Copy constructor with shallow copy of the wrapped list list. As a consequence, modifications of the list created may affect the original one and the other way round. Note that unlike TwoSidedList(List, int) this constructor cannot throw an IllegalStateException.
        Parameters:
        other - another TwoSidedList.

      • TwoSidedList

        public TwoSidedList​(int firstIndex)
        Creates a new empty TwoSidedList which starts growing with index firstIndex. Note that unlike TwoSidedList(List, int) this constructor cannot throw an IllegalStateException.
        Parameters:
        firstIndex - the index where this list starts growing.

    • Method Detail

      • create

        public static <E> TwoSidedList<E> create​(java.util.List<? extends E> list,
                                         int firstIndex)
        Creates a new TwoSidedList containing the elements of list in proper sequence with first index given by firstIndex.
        Parameters:
        list - the list wrapped by this twosided list. Changes to list do not influence this twosided list.
        firstIndex - the index where this list starts growing.
        Throws:
        java.lang.IllegalStateException - if list is so long and firstIndex is so large that minFreeIndex() would overrun.

      • create

        public static <E> TwoSidedList<E> create​(java.util.List<? extends E> list)
        Creates a new TwoSidedList containing the elements of list in proper sequence.
        Parameters:
        list - the list wrapped by this twosided list. Changes to list do not influence this twosided list.

      • create

        public static <E> TwoSidedList<E> create​(TwoSidedList<? extends E> other)
        Creates a new TwoSidedList as a copy of other copying also the wrapped list list. As a consequence, the list created and the original one act independently. Note that unlike TwoSidedList(List, int) this constructor cannot throw an IllegalStateException.
        Parameters:
        other - another TwoSidedList.

      • checkRange

        void checkRange​(int ind)
        Checks whether index ind is in range and throws an appropriate exception if not.
        Parameters:
        ind - the index to be checked.
        Throws:
        java.lang.IndexOutOfBoundsException - if not firstIndex() <= ind < minFreeIndex() with message "Index: <ind> Range: <firstIndex> - <minFreeIndex()> exclusively. " .

      • checkRange

        private void checkRange​(int ind,
                        TwoSidedList.Direction dir)
        Checks whether index ind is in range and throws an appropriate exception if not.
        Parameters:
        ind - the index to be checked.
        dir - the direction in which this twosided list may grow.
        Throws:
        java.lang.IndexOutOfBoundsException -
        • for dir == Left2Right if not firstIndex() <= ind < minFreeIndex()+1.
        • for dir == Right2Left if not firstIndex()-1 <= ind < minFreeIndex().
        The message is always the same: "Index: <ind>Range:<firstIndex> - <minFreeIndex()>exclusively. " .
        See Also:
        add(int, Object, Direction), addAll(int, Collection, Direction)

      • checkRange

        private void checkRange​(java.lang.String fromToNothing,
                        int ind,
                        int min,
                        int maxP)
        Checks whether index ind is in range and throws an appropriate exception if not.
        Parameters:
        fromToNothing - either "", "from" or "to". The latter two cases are used only in subList(int,int) to check the range of the start index and of the end index of the sublist to be created.
        ind - the index to be checked.
        min - the minimal value for ind accepted.
        maxP - one plus the maximal value for ind accepted.
        Throws:
        java.lang.IndexOutOfBoundsException - if not min >= ind < maxP. The message is "Index: <ind> Range: <firstIndex> - <minFreeIndex()> exclusively. " preceeded by fromToNothing.

      • decFirstIndex

        private void decFirstIndex()
        Decrements firstIndex if possible; otherwise throws an exception. This method is used by methods adding objects at the head of this list. The error message is tailored to this usage.
        Throws:
        java.lang.IllegalStateException - if firstIndex == Integer.MIN_VALUE adding an element would cause index underrun.

      • incFirstIndex

        private void incFirstIndex()
        Increments firstIndex if possible; otherwise throws an exception. This method is used by methods removing objects from the head of this list. The error message is tailored to this usage.
        Throws:
        java.lang.IllegalStateException - if firstIndex == Integer.MAX_VALUE removing an element would cause index overrun.

      • subFirstIndex

        private void subFirstIndex​(int numAdded)
        Subtracts numAdded from firstIndex if possible; otherwise throws an exception. This method is used by methods adding objects at the head of this list. The error message is tailored to this usage.
        Throws:
        java.lang.IllegalStateException - if adding numAdded objects at the head of this list would cause underrun of firstIndex.

      • checkMinFreeIndex

        void checkMinFreeIndex​(int numAdded)
        Checks whether adding numAdded objects to this list **** or at the tail of this list would cause overrun of minFreeIndex().
        Throws:
        java.lang.IllegalStateException - if adding numAdded objects to this list **** or at the tail of this list would cause overrun of minFreeIndex().

      • firstIndex

        public int firstIndex()
        Returns firstIndex.

      • firstIndex

        public void firstIndex​(int firstIndex)
        Sets firstIndex according to the parameter.

      • minFreeIndex

        public int minFreeIndex()

      • shiftRight

        public int shiftRight​(int num)
        Shifts this list num indices to the right.
        Parameters:
        num - the number of shifts to the right to be performed on this list. A negative sign signifies a shift to the left.
        Returns:
        The new first index.
        Throws:
        java.lang.IllegalStateException - if shifting would cause overrun of minFreeIndex() (occuring for proper shift to the right) or underrun of firstIndex() (occuring for proper shift to the left).

      • list

        public java.util.List<E> list()

      • size

        public int size()
        Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. **** gives rise to malfunction. ****
        Specified by:
        size in interface java.util.Collection<E>
        Specified by:
        size in interface java.util.List<E>
        Returns:
        an int value

      • isEmpty

        public boolean isEmpty()
        Returns true if this list contains no elements.
        Specified by:
        isEmpty in interface java.util.Collection<E>
        Specified by:
        isEmpty in interface java.util.List<E>
        Returns:
        whether this list contains no elements as a boolean value.

      • contains

        public boolean contains​(java.lang.Object obj)
        Returns whether this list contains the specified element. More formally, returns true if and only if this list contains at least one element obj such that (o==null ? e==null : o.equals(e)).
        Specified by:
        contains in interface java.util.Collection<E>
        Specified by:
        contains in interface java.util.List<E>
        Parameters:
        obj - an Object value
        Returns:
        a boolean value
        Throws:
        java.lang.ClassCastException - if the class of obj is incompatible with list.
        java.lang.NullPointerException - if obj == null and list does not permit null elements.

      • indexOf

        public int indexOf​(java.lang.Object obj)
        Returns the index of the first occurrence of the specified element obj in this list, or firstIndex()-1 if this list does not contain the element. More formally, returns the lowest index i such that (obj==null ? get(i)==null : obj.equals(get(i))), or firstIndex()-1 if there is no such index.

        CAUTION:

        • This breaks **** "extends" contract for the interface List: Test for "element obj not in list" is no longer this.indexOf(obj) == -1 but this.indexOf(obj) < this.firstIndex()-1. This is an extension in that wrapping an ordinary list in a twosided list is by specifying firstIndex() == 0 (see TwoSidedList(List list)).
        • Note that for firstIndex() == Integer.MIN_VALUE firstIndex()-1 > firstIndex().
        Specified by:
        indexOf in interface java.util.List<E>
        Parameters:
        obj - an Object value
        Returns:
        • the index of the first occurrence of obj if this object is in this list. In this case, the return value is within the range firstIndex()..firstFreeIndex()-1.
        • firstIndex()-1 if obj is not in this list.

      • lastIndexOf

        public int lastIndexOf​(java.lang.Object obj)
        Returns the index of the last occurrence of the specified element obj in this list, or firstIndex()-1 if this list does not contain the element. More formally, returns the highest index i such that (obj==null ? get(i)==null : obj.equals(get(i))), or firstIndex()-1 if there is no such index.

        CAUTION:

        • This breaks **** "extends" contract for the interface List: Test for "element obj not in list" is no longer this.indexOf(obj) == -1 but this.indexOf(obj) < this.firstIndex()-1. This is an extension in that wrapping an ordinary list in a twosided list is by specifying firstIndex() == 0 (see TwoSidedList(List list)).
        • Note that for firstIndex() == Integer.MIN_VALUE firstIndex()-1 > firstIndex().
        **** one may expect that in case the specified object in not in the list 1+ the highest index is returned. this is in general not the case.
        Specified by:
        lastIndexOf in interface java.util.List<E>
        Parameters:
        obj - an Object value
        Returns:
        • the index of the last occurrence of obj if this object is in this list. In this case, the return value is within the range firstIndex()..firstFreeIndex()-1.
        • firstIndex()-1 if obj is not in this list.

      • toArray

        public java.lang.Object[] toArray()
        Note that this generalizes the contract of the underlying interface: Instead of this.toArray[i] == this.get(i) now only this.toArray[i] == this.get(i-firstIndex()). Equality includes that the left hand side throws an exception if and only if so does te right hand side.
        Specified by:
        toArray in interface java.util.Collection<E>
        Specified by:
        toArray in interface java.util.List<E>
        Returns:
        an Object[] containing all elements in proper sequence.

      • toArray

        public <E> E[] toArray​(E[] objArr)
        Note that this generalizes the contract of the underlying interface: Instead of this.toArray[i] == this.get(i) now only this.toArray[i] == this.get(i-firstIndex()). Equality includes that the left hand side throws an exception if and only if so does te right hand side.
        Specified by:
        toArray in interface java.util.Collection<E>
        Specified by:
        toArray in interface java.util.List<E>
        Parameters:
        objArr - an Object[] value
        Returns:
        an Object[] value

      • get

        public E get​(int ind)
        Returns the element at the specified position in this list.
        Specified by:
        get in interface java.util.List<E>
        Parameters:
        ind - the index of the element to return as an int value.
        Returns:
        the element at the specified position in this list.
        Throws:
        java.lang.IndexOutOfBoundsException - as described for checkRange(int)

      • set

        public E set​(int ind,
             E obj)
        Replaces the element at the indth position in this list with the specified element (optional operation).
        Specified by:
        set in interface java.util.List<E>
        Parameters:
        ind - the index of the element to replace as an int value.
        obj - the element to be stored at the specified position.
        Returns:
        the element previously at the indth position
        Throws:
        java.lang.UnsupportedOperationException - if the set operation is not supported by list.
        java.lang.ClassCastException - if the class of obj prevents it from being added to list.
        java.lang.NullPointerException - if obj == null and list does not permit null elements.
        java.lang.IllegalArgumentException - if some property of obj prevents it from being added to list.
        java.lang.IndexOutOfBoundsException - as described for checkRange(int)

      • add

        public boolean add​(E obj)
        Not supported by this implementation. **** breaks contract
        Specified by:
        add in interface java.util.Collection<E>
        Specified by:
        add in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use addFirst(E) and addLast(E) instead.

      • addFirst

        public boolean addFirst​(E obj)
        Adds obj at the beginning of this list. The first index returned by firstIndex() is decremented.
        Parameters:
        obj - the E object to be added.
        Returns:
        true by specification.
        Throws:
        java.lang.UnsupportedOperationException - if the add(int,E) operation is not supported by list.
        java.lang.ClassCastException - if the class of obj prevents it from being added to list.
        java.lang.NullPointerException - if obj == null and list does not permit null elements.
        java.lang.IllegalArgumentException - if some property of obj prevents it from being added to list.
        java.lang.IllegalStateException - if firstIndex == Integer.MIN_VALUE adding an element would cause index underrun.

      • addLast

        public boolean addLast​(E obj)
        Adds obj at the end of this list. The first index returned by firstIndex() remains unchanged.
        Parameters:
        obj - the E object to be added.
        Returns:
        true by specification.
        Throws:
        java.lang.UnsupportedOperationException - if the add(E) operation is not supported by list.
        java.lang.ClassCastException - if the class of obj prevents it from being added to list.
        java.lang.NullPointerException - if obj == null and list does not permit null elements.
        java.lang.IllegalArgumentException - if some property of obj prevents it from being added to list.
        java.lang.IllegalStateException - if adding objects to this list would cause overrun of minFreeIndex().

      • add

        public void add​(int ind,
                E obj)
        Not supported by this implementation. **** breaks contract
        Specified by:
        add in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use add(int,Object,Direction) instead.

      • add

        public void add​(int ind,
                E obj,
                TwoSidedList.Direction dir)
        Inserts obj at the specified position ind in this list (optional operation). Shifts the element currently at that position (if any) and any following/preceeding elements to the direction dir (increments/decrements their indices).
        Parameters:
        ind - the index where to insert obj. After having performed this operation, ind is the index of obj.
        obj - the E element to be inserted.
        dir - determines the direction to shift the list.
        • Left2Right: shifts all subsequent objects in this list starting with index ind to the right adding one to their indices.
        • Right2Left: shifts all objects in this list to index ind to the left subtracting one from their indices.
        Throws:
        java.lang.UnsupportedOperationException - if the add operation is not supported by list.
        java.lang.ClassCastException - if the class of obj prevents it from being added to list.
        java.lang.NullPointerException - if obj == null and list does not permit null elements.
        java.lang.IllegalArgumentException - if some property of obj prevents it from being added to list.
        java.lang.IndexOutOfBoundsException - as described for checkRange(int,Direction)

      • remove

        public E remove​(int ind)
        Not supported by this implementation. **** breaks contract
        Specified by:
        remove in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use remove(int,Direction) instead.

      • remove

        public E remove​(int ind,
                TwoSidedList.Direction dir)
        Removes the element at the specified position in this list (optional operation). Shifts any following/preceeding elements to the direction dir (decrements/increments their indices). Returns the element that was removed from the list.
        Parameters:
        ind - the index of the element to be removed as an int value.
        Returns:
        the element previously at the specified position.
        Throws:
        java.lang.UnsupportedOperationException - if the remove(int) operation is not supported by list.
        java.lang.IndexOutOfBoundsException - as described for checkRange(int)

      • remove

        public boolean remove​(java.lang.Object obj)
        Not supported by this implementation. **** breaks contract
        Specified by:
        remove in interface java.util.Collection<E>
        Specified by:
        remove in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use removeFirst(Object) and removeLast(Object) instead.

      • removeFirst

        public boolean removeFirst​(java.lang.Object obj)
        Removes the first occurrence of obj from this list, if present (optional operation). If this list does not contain obj, it is unchanged. More formally, removes the element with the lowest index i such that (obj==null ? get(i)==null : obj.equals(get(i))) (if such an element exists). Returns true if this list contained the specified element (or equivalently, if this list changed as a result of the call). The first index returned by firstIndex() remains unchanged.
        Parameters:
        obj - the element to be removed from this list, if present.
        Returns:
        whether this list contained the specified element
        Throws:
        java.lang.UnsupportedOperationException - if the remove(Object) operation is not supported by list.

      • removeLast

        public boolean removeLast​(java.lang.Object obj)
        Removes the last occurrence of obj from this list, if present (optional operation). If this list does not contain obj, it is unchanged. More formally, removes the element with the highest index i such that (obj==null ? get(i)==null : obj.equals(get(i))) (if such an element exists). Returns true if this list contained the specified element (or equivalently, if this list changed as a result of the call). The first index returned by firstIndex() is incremented if really an object was removed.
        Parameters:
        obj - the element to be removed from this list, if present.
        Returns:
        whether this list contained the specified element
        Throws:
        java.lang.UnsupportedOperationException - if the remove(int) **** not remove(Object) operation is not supported by list.

      • clear

        public void clear()
        Removes all of the elements from this list (optional operation). The list will be empty after this call returns and firstIndex is unmodified.
        Specified by:
        clear in interface java.util.Collection<E>
        Specified by:
        clear in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - if the clear operation is not supported by list.

      • addAllFirst

        public boolean addAllFirst​(java.util.Collection<? extends E> coll)
        Adds obj at the beginning of this list. in the order that they are returned by coll's iterator (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (Note that this will occur if coll is this list, and it's nonempty.) The first index returned by firstIndex() is reduced by coll's size.
        Parameters:
        coll - a Collection value
        Returns:
        whether this list changed as a result of the call as a boolean value.
        Throws:
        java.lang.UnsupportedOperationException - if the addAll operation is not supported by this list.
        java.lang.ClassCastException - if the class of an element of the specified collection prevents it from being added to list.
        java.lang.NullPointerException - if the specified collection contains one or more null elements and list does not permit null elements or if the specified collection is null
        java.lang.IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
        java.lang.IllegalStateException - if adding numAdded objects at the head of this list would cause underrun of firstIndex.

      • addAllLast

        public boolean addAllLast​(java.util.Collection<? extends E> coll)
        Appends all of the elements in coll to the end of this list, in the order that they are returned by coll's iterator (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (Note that this will occur if coll is this list, and it's nonempty.) The first index returned by firstIndex() remains unchanged.
        Parameters:
        coll - another Collection.
        Returns:
        whether this list changed as a result of the call as a boolean value.
        Throws:
        java.lang.UnsupportedOperationException - if the addAll operation is not supported by this list.
        java.lang.ClassCastException - if the class of an element of the specified collection prevents it from being added to list.
        java.lang.NullPointerException - if the specified collection contains one or more null elements and list does not permit null elements or if the specified collection is null
        java.lang.IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
        java.lang.IllegalStateException - if adding numAdded objects to this list **** or at the tail of this list would cause overrun of minFreeIndex().

      • addAll

        public boolean addAll​(int ind,
                      java.util.Collection<? extends E> coll)
        Not supported by this implementation.
        Specified by:
        addAll in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use addAll(int,Collection,Direction) instead.

      • addAll

        public boolean addAll​(int ind,
                      java.util.Collection<? extends E> coll,
                      TwoSidedList.Direction dir)
        Inserts all of the elements in coll into this list at the specified position (optional operation). Shifts the elements currently at that positions (if any) and any following/preceeding elements to the direction dir (increasing/decreasing their indices by coll's size). The new elements will appear in this list in the order that they are returned by the specified collection's iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.)
        Parameters:
        ind - index at which to insert the first element from coll as an int value. CAUTION: Note that ind always references the first element in coll independent from dir.
        coll - a Collection containing elements to be added to this list.
        dir - determines the direction to shift the list.
        • Left2Right: shifts all subsequent objects in this list starting with index ind to the right adding one to their indices.
        • Right2Left: shifts all objects in this list to index ind to the left subtracting one from their indices.
        Returns:
        whether this list changed as a result of the call as a boolean value.
        Throws:
        java.lang.UnsupportedOperationException - if the addAll operation is not supported by this list.
        java.lang.ClassCastException - if the class of an element of coll prevents it from being added to list.
        java.lang.NullPointerException - if the coll contains at least one null element and list does not permit null elements or if coll == null.
        java.lang.IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
        java.lang.IndexOutOfBoundsException - as described for checkRange(int,Direction)
        java.lang.IllegalStateException - if adding coll to this list would cause underrun of firstIndex or overrun of minFreeIndex().

      • iterator

        public java.util.Iterator<E> iterator()
        Specified by:
        iterator in interface java.util.Collection<E>
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in interface java.util.List<E>

      • listIterator

        public java.util.ListIterator<E> listIterator()
        Specified by:
        listIterator in interface java.util.List<E>

      • listIterator

        public java.util.ListIterator<E> listIterator​(int ind)
        ****maybe to be endowed with a direction.
        Specified by:
        listIterator in interface java.util.List<E>
        Parameters:
        ind - an int value
        Returns:
        a ListIterator value
        Throws:
        java.lang.IndexOutOfBoundsException - if not firstIndex() <= ind <= minFreeIndex() with message "Index: <ind> Range: <firstIndex> - <minFreeIndex()> exclusively. " .

      • containsAll

        public boolean containsAll​(java.util.Collection<?> coll)
        Replaces the element at the indth position in this list with the specified element (optional operation).
        Specified by:
        containsAll in interface java.util.Collection<E>
        Specified by:
        containsAll in interface java.util.List<E>
        Parameters:
        coll - a Collection value
        Returns:
        a boolean value
        Throws:
        java.lang.ClassCastException - if the class of one or more elements of coll is incompatible with list.
        java.lang.NullPointerException - if coll contains at least one null element and list is incompatible with null elements or if coll == null.

      • removeAll

        public boolean removeAll​(java.util.Collection<?> coll)
        Not supported by this implementation.
        Specified by:
        removeAll in interface java.util.Collection<E>
        Specified by:
        removeAll in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use removeAll(Collection,Direction) instead.

      • removeAll

        public boolean removeAll​(java.util.Collection<?> coll,
                         TwoSidedList.Direction dir)
        Removes from this list all of its elements that are contained in coll (optional operation). Shifts the elements currently at that position (if any) and any following/preceeding elements to the direction dir (decreasing/increasing their indices by the number of elements removed).
        Parameters:
        coll - a Collection containing elements to be removed from this list.
        dir - determines the direction to shift the list.
        • Left2Right: to close gaps by removing elements shifts all objects preceeding gaps to the right adding one to their indices.
        • Right2Left: to close gaps by removing elements shifts all objects following gaps to the left subtracting one from their indices.
        Returns:
        whether this list changed as a result of the call as a boolean value.
        Throws:
        java.lang.UnsupportedOperationException - if the removeAll operation is not supported by this list.
        java.lang.ClassCastException - if the class of an element of coll is incompatible with list.
        java.lang.NullPointerException - if the coll contains at least one null element and list does not permit null elements or if coll == null.

      • retainAll

        public boolean retainAll​(java.util.Collection<?> coll)
        Not supported by this implementation.
        Specified by:
        retainAll in interface java.util.Collection<E>
        Specified by:
        retainAll in interface java.util.List<E>
        Throws:
        java.lang.UnsupportedOperationException - use retainAll(Collection,Direction) instead.

      • retainAll

        public boolean retainAll​(java.util.Collection<?> coll,
                         TwoSidedList.Direction dir)
        Retains only the elements in this list that are contained in coll (optional operation). In other words, removes from this list all the elements that are not contained in coll. Shifts the elements currently at that position (if any) and any following/preceeding elements to the direction dir (decreasing/increasing their indices by the number of elements removed).
        Parameters:
        coll - a Collection containing elements to be retained in this list.
        dir - determines the direction to shift the list.
        • Left2Right: to close gaps by removing elements shifts all objects preceeding gaps to the right adding one to their indices.
        • Right2Left: to close gaps by removing elements shifts all objects following gaps to the left subtracting one from their indices.
        Returns:
        whether this list changed as a result of the call as a boolean value.
        Throws:
        java.lang.UnsupportedOperationException - if the retainAll operation is not supported by this list.
        java.lang.ClassCastException - if the class of an element of coll is incompatible with list.
        java.lang.NullPointerException - if the coll contains at least one null element and list does not permit null elements or if coll == null.

      • subList

        public java.util.List<E> subList​(int indStart,
                                 int indEnd)
        Returns a view of the portion of this twosided list as a list between the specified fromIndex, inclusive, and toIndex, exclusive.
        Specified by:
        subList in interface java.util.List<E>
        Parameters:
        indStart - low endpoint (inclusive) of the subList to be returned.
        indEnd - high endpoint (exclusive) of the subList to be returned.
        Returns:
        view of the specified range within this list. The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
        Throws:
        java.lang.IndexOutOfBoundsException - if not firstIndex() <= indStart <= indEnd <= minFreeIndex()

      • subList2

        public TwoSidedList<E> subList2​(int indStart,
                                int indEnd)
        Returns a view of the portion of this twosided list between the specified fromIndex, inclusive, and toIndex, exclusive.
        Parameters:
        indStart - low endpoint (inclusive) of the subList to be returned.
        indEnd - high endpoint (exclusive) of the subList to be returned.
        Returns:
        view of the specified range within this list. The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
        Throws:
        java.lang.IndexOutOfBoundsException - see subList(int,int)

      • equals

        public boolean equals​(java.lang.Object obj)
        The given object equals this twosided list if and only if it is as well a TwoSidedList, the two lists wrapped list coincide and either as well the first indices firstIndex coincide. CAUTION: Note that two empty lists with different first index are not equal. This is justified by the fact, that these two become different when the same first element is added to both lists.
        Specified by:
        equals in interface java.util.Collection<E>
        Specified by:
        equals in interface java.util.List<E>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - an Object value
        Returns:
        a boolean value

      • hashCode

        public int hashCode()
        Returns a hash code which conforms with equals(Object).
        Specified by:
        hashCode in interface java.util.Collection<E>
        Specified by:
        hashCode in interface java.util.List<E>
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code as an int value.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • main

        public static void main​(java.lang.String[] args)