goldman.collection.positional
Interface PositionalCollection<E>

All Superinterfaces:
Collection<E>, Iterable<E>
All Known Implementing Classes:
AbstractPositionalCollection, Array, CircularArray, DoublyLinkedList, DynamicArray, DynamicCircularArray, SinglyLinkedList, TrackedArray

public interface PositionalCollection<E>
extends Collection<E>

Often an application needs to maintain a collection of elements that are accessed via their position in a line (with 0 being the position of the first element in the line) or via their location relative to other elements in the line. In a positional collection, the iteration order is given by: position 0, position 1, ..., position n-1.


Method Summary
 void add(int p, E value)
          Inserts value into position p.
 void addFirst(E value)
          Inserts value at the front (position 0) of this collection.
 void addLast(E value)
          Inserts value at the end of this collection (position size).
 void bucketsort(Bucketizer<? super E> bucketizer)
          Sorts this collection using bucket sort with the given bucketizer.
 E get(int p)
          Returns the element at position p.
 void heapsort()
          Sorts this collection with heap sort using the default comparator.
 void heapsort(Comparator<? super E> comp)
          Sorts this collection with heap sort using the provided comparator.
 void insertionsort()
          Sorts this collection with insertion sort using the default comparator.
 void insertionsort(Comparator<? super E> comp)
          Sorts this collection with insertion sort using the default comparator.
 PositionalCollectionLocator<E> iterator()
          Returns a positional collection locator that has been initialized to FORE.
 PositionalCollectionLocator<E> iteratorAtEnd()
          Returns a locator that has been initialized to AFT.
 void mergesort()
          Sorts the positional collection with merge sort using the default comparator.
 void mergesort(Comparator<? super E> comp)
          Sorts this collection with merge sort using the default comparator.
 int positionOf(E value)
          Returns the position of the first occurrence (if any) of an element equivalent to value.
 void quicksort()
          Sorts this collection with quicksort using the default comparator.
 void quicksort(Comparator<? super E> comp)
          Sorts this collection with quick sort using the default comparator.
 void radixsort(Digitizer<? super E> digitizer)
          Sorts this collection using radix sort with the provided digitizer.
 E remove(int p)
          Removes the element at position p and returns it.
 E removeFirst()
          Removes the element at the front (position 0) of this collection and returns it.
 E removeLast()
          Removes the element at the end (position n-1) of this collection and returns it.
 void removeRange(int fromPosition, int toPosition)
          Removes the elements from position fromPosition to position toPosition, inclusive.
 E repositionElementByRank(int r)
          Modifies the positional collection so element in position r is in its proper sorted order when using the default comparator, and returns that element.
 E repositionElementByRank(int r, Comparator<? super E> comp)
          Modifies the positional collection so element in position r is in its proper sorted order when using the provided comparator, and returns this element.
 E set(int p, E value)
          Replaces the element at position p by the given value, and returns the element that had been in position p.
 void swap(int a, int b)
          Interchanges the element at position a with the element at position b.
 void treesort()
          Sorts this collection with tree sort using the default comparator.
 void treesort(Comparator<? super E> comp)
          Sorts this collection with tree sort using the provided comparator.
 
Methods inherited from interface goldman.collection.Collection
accept, add, addAll, checkRep, clear, contains, ensureCapacity, getCapacity, getComparator, getEquivalentElement, getLocator, getSize, isEmpty, remove, retainAll, toArray, toArray, toString, trimToSize
 

Method Detail

add

void add(int p,
         E value)
Inserts value into position p. The position of the elements that were at positions p to size-1 increase by one.


addFirst

void addFirst(E value)
Inserts value at the front (position 0) of this collection. The positions of the existing elements are increased by one.


addLast

void addLast(E value)
Inserts value at the end of this collection (position size).


get

E get(int p)
Returns the element at position p. It is required that 0 ≤ p ≤ size-1 (i.e., that the position exists in the collection). Otherwise a PositionOutOfBoundsException is thrown.


iterator

PositionalCollectionLocator<E> iterator()
Returns a positional collection locator that has been initialized to FORE.

Specified by:
iterator in interface Collection<E>
Specified by:
iterator in interface Iterable<E>

iteratorAtEnd

PositionalCollectionLocator<E> iteratorAtEnd()
Returns a locator that has been initialized to AFT. As with the iterator method, this method also enables navigation.


positionOf

int positionOf(E value)
Returns the position of the first occurrence (if any) of an element equivalent to value. It throws a NoSuchElementException if there is no equivalent element. (The Java collections return -1 when there is no element with the given value, but throwing an exception will better enable a problem to be detected if an application program did not consider the possibility of -1 being returned.)


remove

E remove(int p)
Removes the element at position p and returns it. The positions of the elements originally at positions p+1, ..., size-1 are decremented by 1. It is required that 0 ≤ p ≤ size-1 (i.e., that the given position exists in the current collection). Otherwise a PositionOutOfBoundsException is thrown.


removeFirst

E removeFirst()
Removes the element at the front (position 0) of this collection and returns it. The positions of all other elements are decremented by 1. If the collection is empty, a NoSuchElementException is thrown.


removeLast

E removeLast()
Removes the element at the end (position n-1) of this collection and returns it. If the collection is empty, a NoSuchElementException is thrown.


removeRange

void removeRange(int fromPosition,
                 int toPosition)
Removes the elements from position fromPosition to position toPosition, inclusive. The positions for elements toPosition+1, ..., size-1 are decremented by toPosition - fromPosition + 1 (the number of elements removed). It is required that 0 ≤ fromPositiontoPositionsize - 1. A PositionOutOfBoundsException is thrown when either of the arguments is not a valid position, and an IllegalArgumentException is thrown when fromPos is greater than toPos.


set

E set(int p,
      E value)
Replaces the element at position p by the given value, and returns the element that had been in position p. It is required that 0 ≤ psize-1. Otherwise, a PositionOutOfBoundsException is thrown.


swap

void swap(int a,
          int b)
Interchanges the element at position a with the element at position b. It is required that 0 ≤ asize-1 and 0 ≤ bsize-1. Otherwise, a PositionOutOfBoundsException is thrown.


bucketsort

void bucketsort(Bucketizer<? super E> bucketizer)
Sorts this collection using bucket sort with the given bucketizer.


heapsort

void heapsort()
Sorts this collection with heap sort using the default comparator.


heapsort

void heapsort(Comparator<? super E> comp)
Sorts this collection with heap sort using the provided comparator.


insertionsort

void insertionsort()
Sorts this collection with insertion sort using the default comparator.


insertionsort

void insertionsort(Comparator<? super E> comp)
Sorts this collection with insertion sort using the default comparator.


mergesort

void mergesort()
Sorts the positional collection with merge sort using the default comparator.


mergesort

void mergesort(Comparator<? super E> comp)
Sorts this collection with merge sort using the default comparator.


quicksort

void quicksort()
Sorts this collection with quicksort using the default comparator.


quicksort

void quicksort(Comparator<? super E> comp)
Sorts this collection with quick sort using the default comparator.


radixsort

void radixsort(Digitizer<? super E> digitizer)
Sorts this collection using radix sort with the provided digitizer.


treesort

void treesort()
Sorts this collection with tree sort using the default comparator.


treesort

void treesort(Comparator<? super E> comp)
Sorts this collection with tree sort using the provided comparator.


repositionElementByRank

E repositionElementByRank(int r)
Modifies the positional collection so element in position r is in its proper sorted order when using the default comparator, and returns that element. This method does not completely sort the collection, but it may mutate it.


repositionElementByRank

E repositionElementByRank(int r,
                          Comparator<? super E> comp)
Modifies the positional collection so element in position r is in its proper sorted order when using the provided comparator, and returns this element. This method does not completely sort the collection, but it may mutate it.