TwoSidedList (TestHelpers 1.0-SNAPSHOT API)

java.lang.Object
- eu.simuline.util.TwoSidedList<E>

Type Parameters:

E - the class of the elements of this list. Created: Sun Aug 26 23:25:26 2007

All Implemented Interfaces:

Iterable<E>, Collection<E>, List<E>
```
public final class TwoSidedList<E>
extends Object
implements 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 and 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 and Description

private int firstIndex
The first index in this TwoSidedList.

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

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

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`add(E obj)` Not supported by this implementation. **** breaks contract
`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`	`addAll(Collection<? extends E> coll)` Not supported by this implementation.
`boolean`	`addAll(int ind, Collection<? extends E> coll)` Not supported by this implementation.
`boolean`	`addAll(int ind, Collection<? extends E> coll, TwoSidedList.Direction dir)` Inserts all of the elements in `coll` into this list at the specified position (optional operation).
`boolean`	`addAllFirst(Collection<? extends E> coll)` Adds `obj` at the beginning of this list.
`boolean`	`addAllLast(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(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(Object obj)` Returns whether this list contains the specified element.
`boolean`	`containsAll(Collection<?> coll)` Replaces the element at the `ind`th position in this list with the specified element (optional operation).
`static <E> TwoSidedList<E>`	`create(List<? extends E> list)` Creates a new `TwoSidedList` containing the elements of `list` in proper sequence.
`static <E> TwoSidedList<E>`	`create(List<? extends E> list, int firstIndex)` Creates a new `TwoSidedList` containing the elements of `list` in proper sequence with first index given by `firstIndex`.
`static <E> TwoSidedList<E>`	`create(TwoSidedList<? extends E> other)` Creates a new `TwoSidedList` as a copy of `other` copying also the wrapped list `list`.
`private void`	`decFirstIndex()` Decrements `firstIndex` if possible; otherwise throws an exception.
`boolean`	`equals(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(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.
`Iterator<E>`	`iterator()`
`int`	`lastIndexOf(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.
`List<E>`	`list()`
`ListIterator<E>`	`listIterator()`
`ListIterator<E>`	`listIterator(int ind)` ****maybe to be endowed with a direction.
`static void`	`main(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(Object obj)` Not supported by this implementation. **** breaks contract
`boolean`	`removeAll(Collection<?> coll)` Not supported by this implementation.
`boolean`	`removeAll(Collection<?> coll, TwoSidedList.Direction dir)` Removes from this list all of its elements that are contained in `coll` (optional operation).
`boolean`	`removeFirst(Object obj)` Removes the first occurrence of `obj` from this list, if present (optional operation).
`boolean`	`removeLast(Object obj)` Removes the last occurrence of `obj` from this list, if present (optional operation).
`boolean`	`retainAll(Collection<?> coll)` Not supported by this implementation.
`boolean`	`retainAll(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 `ind`th 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.
`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.
`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())`.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List
replaceAll, sort, spliterator

Methods inherited from interface java.util.Collection
parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable
forEach

- Field Detail
  - list
```
private 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(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. 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:
    
    IllegalStateException - if list is so long and firstIndex is so large that minFreeIndex() would overrun.
  - TwoSidedList
```
public TwoSidedList(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. 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(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:
    
    IllegalStateException - if list is so long and firstIndex is so large that minFreeIndex() would overrun.
  - create
```
public static <E> TwoSidedList<E> create(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:
    
    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:
    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),
  - checkRange
```
private void checkRange(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:
    
    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:
    
    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:
    
    IllegalStateException - if firstIndex == Integer.MAX_VALUE removing an element would cause index overrun.
  - checkIncMinFreeIndex
```
void checkIncMinFreeIndex()
```
    Checks whether incrementing minFreeIndex() would cause overrun of minFreeIndex().
    
    Throws:
    
    IllegalStateException - if incrementing minFreeIndex() would cause overrun of minFreeIndex().
  - 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:
    
    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:
    
    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:
    
    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 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 Collection<E>
    
    Specified by:
    
    size in interface List<E>
    
    Returns:
    
    an int value
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if this list contains no elements.
    
    Specified by:
    
    isEmpty in interface Collection<E>
    
    Specified by:
    
    isEmpty in interface List<E>
    
    Returns:
    
    whether this list contains no elements as a boolean value.
  - contains
```
public boolean contains(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 Collection<E>
    
    Specified by:
    
    contains in interface List<E>
    
    Parameters:
    
    obj - an Object value
    
    Returns:
    
    a boolean value
    
    Throws:
    
    ClassCastException - if the class of obj is incompatible with list.
    
    NullPointerException - if obj == null and list does not permit null elements.
  - indexOf
```
public int indexOf(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 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(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 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 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 Collection<E>
    
    Specified by:
    
    toArray in interface 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 Collection<E>
    
    Specified by:
    
    toArray in interface 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 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:
    
    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 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:
    
    UnsupportedOperationException - if the set operation is not supported by list.
    
    ClassCastException - if the class of obj prevents it from being added to list.
    
    NullPointerException - if obj == null and list does not permit null elements.
    
    IllegalArgumentException - if some property of obj prevents it from being added to list.
    
    IndexOutOfBoundsException - as described for checkRange(int)
  - add
```
public boolean add(E obj)
```
    Not supported by this implementation. **** breaks contract
    
    Specified by:
    
    add in interface Collection<E>
    
    Specified by:
    
    add in interface List<E>
    
    Throws:
    
    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:
    
    UnsupportedOperationException - if the add(int,E) operation is not supported by list.
    
    ClassCastException - if the class of obj prevents it from being added to list.
    
    NullPointerException - if obj == null and list does not permit null elements.
    
    IllegalArgumentException - if some property of obj prevents it from being added to list.
    
    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:
    
    UnsupportedOperationException - if the add(E) operation is not supported by list.
    
    ClassCastException - if the class of obj prevents it from being added to list.
    
    NullPointerException - if obj == null and list does not permit null elements.
    
    IllegalArgumentException - if some property of obj prevents it from being added to list.
    
    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 List<E>
    
    Throws:
    
    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:
    
    UnsupportedOperationException - if the add operation is not supported by list.
    
    ClassCastException - if the class of obj prevents it from being added to list.
    
    NullPointerException - if obj == null and list does not permit null elements.
    
    IllegalArgumentException - if some property of obj prevents it from being added to list.
    
    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 List<E>
    
    Throws:
    
    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:
    
    UnsupportedOperationException - if the remove(int) operation is not supported by list.
    
    IndexOutOfBoundsException - as described for checkRange(int)
  - remove
```
public boolean remove(Object obj)
```
    Not supported by this implementation. **** breaks contract
    
    Specified by:
    
    remove in interface Collection<E>
    
    Specified by:
    
    remove in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - use removeFirst(Object) and removeLast(Object) instead.
  - removeFirst
```
public boolean removeFirst(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:
    
    UnsupportedOperationException - if the remove(Object) operation is not supported by list.
  - removeLast
```
public boolean removeLast(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:
    
    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 Collection<E>
    
    Specified by:
    
    clear in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - if the clear operation is not supported by list.
  - addAll
```
public boolean addAll(Collection<? extends E> coll)
```
    Not supported by this implementation.
    
    Specified by:
    
    addAll in interface Collection<E>
    
    Specified by:
    
    addAll in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - use addAllFirst(java.util.Collection<? extends E>) and addAllLast(java.util.Collection<? extends E>) instead.
  - addAllFirst
```
public boolean addAllFirst(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:
    
    UnsupportedOperationException - if the addAll operation is not supported by this list.
    
    ClassCastException - if the class of an element of the specified collection prevents it from being added to list.
    
    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
    
    IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
    
    IllegalStateException - if adding numAdded objects at the head of this list would cause underrun of firstIndex.
  - addAllLast
```
public boolean addAllLast(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:
    
    UnsupportedOperationException - if the addAll operation is not supported by this list.
    
    ClassCastException - if the class of an element of the specified collection prevents it from being added to list.
    
    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
    
    IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
    
    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,
                      Collection<? extends E> coll)
```
    Not supported by this implementation.
    
    Specified by:
    
    addAll in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - use addAll(int,Collection,Direction) instead.
  - addAll
```
public boolean addAll(int ind,
                      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:
    
    UnsupportedOperationException - if the addAll operation is not supported by this list.
    
    ClassCastException - if the class of an element of coll prevents it from being added to list.
    
    NullPointerException - if the coll contains at least one null element and list does not permit null elements or if coll == null.
    
    IllegalArgumentException - if some property of an element of the specified collection prevents it from being added to list.
    
    IndexOutOfBoundsException - as described for checkRange(int,Direction)
    
    IllegalStateException - if adding coll to this list would cause underrun of firstIndex or overrun of minFreeIndex().
  - iterator
```
public Iterator<E> iterator()
```
    Specified by:
    
    iterator in interface Iterable<E>
    
    Specified by:
    
    iterator in interface Collection<E>
    
    Specified by:
    
    iterator in interface List<E>
  - listIterator
```
public ListIterator<E> listIterator()
```
    Specified by:
    
    listIterator in interface List<E>
  - listIterator
```
public ListIterator<E> listIterator(int ind)
```
    ****maybe to be endowed with a direction.
    
    Specified by:
    
    listIterator in interface List<E>
    
    Parameters:
    
    ind - an int value
    
    Returns:
    
    a ListIterator value
    
    Throws:
    
    IndexOutOfBoundsException - if not firstIndex() <= ind <= minFreeIndex() with message "Index: <ind> Range: <firstIndex> - <minFreeIndex()> exclusively. ".
  - containsAll
```
public boolean containsAll(Collection<?> coll)
```
    Replaces the element at the indth position in this list with the specified element (optional operation).
    
    Specified by:
    
    containsAll in interface Collection<E>
    
    Specified by:
    
    containsAll in interface List<E>
    
    Parameters:
    
    coll - a Collection value
    
    Returns:
    
    a boolean value
    
    Throws:
    
    ClassCastException - if the class of one or more elements of coll is incompatible with list.
    
    NullPointerException - if coll contains at least one null element and list is incompatible with null elements or if coll == null.
  - removeAll
```
public boolean removeAll(Collection<?> coll)
```
    Not supported by this implementation.
    
    Specified by:
    
    removeAll in interface Collection<E>
    
    Specified by:
    
    removeAll in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - use removeAll(Collection,Direction) instead.
  - removeAll
```
public boolean removeAll(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:
    
    UnsupportedOperationException - if the removeAll operation is not supported by this list.
    
    ClassCastException - if the class of an element of coll is incompatible with list.
    
    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(Collection<?> coll)
```
    Not supported by this implementation.
    
    Specified by:
    
    retainAll in interface Collection<E>
    
    Specified by:
    
    retainAll in interface List<E>
    
    Throws:
    
    UnsupportedOperationException - use retainAll(Collection,Direction) instead.
  - retainAll
```
public boolean retainAll(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:
    
    UnsupportedOperationException - if the retainAll operation is not supported by this list.
    
    ClassCastException - if the class of an element of coll is incompatible with list.
    
    NullPointerException - if the coll contains at least one null element and list does not permit null elements or if coll == null.
  - subList
```
public 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 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:
    
    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:
    
    IndexOutOfBoundsException - see subList(int,int)
  - equals
```
public boolean equals(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 Collection<E>
    
    Specified by:
    
    equals in interface List<E>
    
    Overrides:
    
    equals in class 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 Collection<E>
    
    Specified by:
    
    hashCode in interface List<E>
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code as an int value.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - main
```
public static void main(String[] args)
```

Class TwoSidedList<E>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.List

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Field Detail

list

firstIndex

Constructor Detail

TwoSidedList

TwoSidedList

TwoSidedList

TwoSidedList

Method Detail

create

create

create

checkRange

checkRange

checkRange

decFirstIndex

incFirstIndex

checkIncMinFreeIndex

subFirstIndex

checkMinFreeIndex

firstIndex

firstIndex

minFreeIndex

shiftRight

list

size

isEmpty

contains

indexOf

lastIndexOf

toArray

toArray

get

set

add

addFirst

addLast

add

add

remove

remove

remove

removeFirst

removeLast

clear

addAll

addAllFirst

addAllLast

addAll

addAll

iterator

listIterator

listIterator

containsAll

removeAll

removeAll

retainAll

retainAll

subList

subList2

equals

hashCode

toString

main