org.palo.api.impl.utils
Class ArrayListInt

java.lang.Object
  extended by org.palo.api.impl.utils.ArrayListInt

public final class ArrayListInt
extends java.lang.Object

ArrayListInt implements a java.util.List alike container for efficient storing of a single primitive java-type, avoiding the overhead of storing wrapper objects. The interfaces Collection and List are not implemented intentionally, since this class doesn't work with subtypes of Object. Nevertheless the method signatures and the semantics are the same. An advantage of not implementing the interface is that we don't have to use virtual invocation and can declare methods as final, which gives us superior performance. Things not implemented that can be found in the standard ArrayList include: public ArrayList(Collection); In addition to the above methods, the provided ArrayListInt.Iterator and ArrayListInt.ListIterator do not have a remove() method. You can use the container structure itself in case you need to remove elements. The iterators will throw the runtime-exception ListModifiedException in case they detect themselves that they were modified since the iterator was instanciated. This is NOT RELIABLE in the context of a multithreaded application. Only proper synchronization provides memory-barriers in the java programming language. Thus this is merely a helpful technique that might detect errors in concurrent programming. Only in a serialized programming context, the programmer can rely on the exception being generated each time the array is illegaly modified.

Version:
$Id: ArrayListInt.html,v 1.8 2009/07/09 11:01:47 ArndHouben Exp $

Nested Class Summary
 class ArrayListInt.Iterator
          ArrayListInt.Iterator provides a simple forware iterator with basic versioning.
 class ArrayListInt.ListIterator
          ArrayListInt.ListIterator is a bidirectional iterator with basic versioning.
 
Constructor Summary
ArrayListInt()
          Constructs a new arraylist with a default capacity of 8 elements.
ArrayListInt(int initialcapacity)
          Constructs a new arraylist with the given initial capacity.
ArrayListInt(int[] array)
          Constructs a new arraylist and initializes the elements with the contents from the array passed as argument.
ArrayListInt(int n, int element)
          Constructs a new arraylist and fills it with n copies of the specified element.
 
Method Summary
 boolean add(int element)
          Appends the element at the end of the arraylist.
 void add(int index, int element)
          Insert the element into the arraylist at the specified position.
 boolean addAll(ArrayListInt otherlist)
          Appends all of the elements of another list after the end of this arraylist.
 int binarySearch(int element)
          Performs a binary search on the array.
 void clear()
          Removes all elements from the arraylist.
 java.lang.Object clone()
          Makes a shallow copy of arraylist.
 boolean contains(int element)
          Checks whether an element is contained in the arraylist.
 void ensureCapacity(int newcapacity)
          Restructure this arraylist so that its internal capacity is equal or larger than the passed argument.
 int get(int index)
          Retrieves the element at the given position in the arraylist.
 int indexOf(int element)
          Forward search for an element in the arraylist starting at index 0.
 boolean isEmpty()
          Tests whether this arraylist is empty or not.
 ArrayListInt.Iterator iterator()
          Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this: ArrayListInt.Iterator it = alist.iterator(); while (it.hasNext()) { int l = li.previous (); System.out.println (" : " + l); } For backwards iteration @see ListIterator.
 int lastIndexOf(int element)
          Seeks an element backwards from the end of the arraylist.
 ArrayListInt.ListIterator listIterator()
          Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this: ArrayListInt.ListIterator it = alist.listIterator(); while (it.hasNext()) { int l = li.next (); System.out.println (" : " + l); } Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious
 ArrayListInt.ListIterator listIterator(int index)
          Returns a simple forward iterator with user-specified starting position which can be used to retrieve the contents of the arraylist in reverse order like this: ArrayListInt.ListIterator it = alist.listIterator(alist.size()); while (it.hasPrevious()) { int l = li.previous (); System.out.println (" : " + l); } Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious
 int remove(int index)
          Removes the element at the specified position.
 void removeRange(int from, int to)
          Removes the elements whose index is between from (inclusive) and to(exclusive).
 boolean replaceAll(int element, int newElement)
          Replaces all occurences of element by newElement.
 void reverse()
          Reverses the order of the arraylist.
 int set(int index, int element)
          Sets the element at the given position in the arraylist.
 int size()
          Queries the size of this arraylist.
 void sort()
          Sorts the array in ascending order using quicksort.
 void sort(boolean descending)
          Sorts the array in ascending or descending order using quicksort.
 int[] toArray()
          Allocates an array whose length is equal to the size() of this arraylist and then copies the contents of the arraylist into it.
 int[] toArray(int[] dest)
          This copies the elements from this array to the passed array-reference.
 java.lang.String toString()
          Returns a string-representation of the array.
 void trimToSize()
          Trims this array's capacity to its actual size.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ArrayListInt

public ArrayListInt(int initialcapacity)
Constructs a new arraylist with the given initial capacity.

Parameters:
initialcapacity - the initial capacity of the array.
Throws:
InvalidArgumentException - if the initialcapacity specified is less than 1.

ArrayListInt

public ArrayListInt()
Constructs a new arraylist with a default capacity of 8 elements.


ArrayListInt

public ArrayListInt(int n,
                    int element)
Constructs a new arraylist and fills it with n copies of the specified element.

Parameters:
n - number of entries to fill with the default element
element - default element

ArrayListInt

public ArrayListInt(int[] array)
Constructs a new arraylist and initializes the elements with the contents from the array passed as argument. The capacity of the arraylist is set to exactly the length of the source array.

Parameters:
array - the array from which the arraylist is initialized.
Method Detail

trimToSize

public final void trimToSize()
Trims this array's capacity to its actual size. This means the internal storage is adjusted to be just large enough hold as many elements as there are in the arraylist. The lower limit on the array's capacity is 1. Invoking this method on an empty list will not reduce the internal capacity below the threshold value of 1.


ensureCapacity

public final void ensureCapacity(int newcapacity)
Restructure this arraylist so that its internal capacity is equal or larger than the passed argument.

Parameters:
newcapacity - the new capacity of the arraylist. Specifying a negative cacacity will cause this method to have no effect.

size

public final int size()
Queries the size of this arraylist. The size denotes the number of elements that are stored inside the datastructure.

Returns:
the size of this arraylist.

isEmpty

public final boolean isEmpty()
Tests whether this arraylist is empty or not.

Returns:
true if this arraylist has 0 elements and false if this arraylist has a size greater than 0.

contains

public final boolean contains(int element)
Checks whether an element is contained in the arraylist.

Parameters:
element - element to look for in the arraylist.
Returns:
true if the element was found inside the list, otherwise false is returned.

indexOf

public final int indexOf(int element)
Forward search for an element in the arraylist starting at index 0.

Parameters:
element - element to look for in the arraylist.
Returns:
index counted from the beginning of the arraylist where the element was found. In case the element is not found in the arraylist the value -1 is returned.

lastIndexOf

public final int lastIndexOf(int element)
Seeks an element backwards from the end of the arraylist.

Parameters:
element - element to look for in the arraylist.
Returns:
index counted from the beginning of the arraylist where the element was found. In case the element is not found in the arraylist the value -1 is returned.

get

public final int get(int index)
Retrieves the element at the given position in the arraylist. For efficiency considerations there is no custom exception thrown. If an illegal element index is specified a java.lang.ArrayIndexOutofBoundsException will be thrown.

Parameters:
index - the index of the element that should be returned.
Returns:
the value at the given index.
Throws:
InvalidArgumentException - thrown if the argument points to an illegal index less than 0 or equal-or-greater than the current size of the arraylist.

set

public final int set(int index,
                     int element)
Sets the element at the given position in the arraylist.

Parameters:
index - the index of the element that should be returned.
element - the element to set at the specified position
Returns:
the value previously stored at the given index.
Throws:
IllegalElementException - thrown if the argument points to an illegal index less than 0 or equal-or-greater than the current size of the arraylist.

add

public final boolean add(int element)
Appends the element at the end of the arraylist.

Parameters:
element - the element to append to the arraylist
Returns:
always true by contract.

addAll

public final boolean addAll(ArrayListInt otherlist)
Appends all of the elements of another list after the end of this arraylist. If the other list is null or has zero-size, then this arraylist remains unchanged.

Parameters:
otherlist - the list whose elements are to be appended.
Returns:
true if this list was changed by the call.

add

public final void add(int index,
                      int element)
Insert the element into the arraylist at the specified position.

Parameters:
index - the index where to insert.
element - the element to insert into the arraylist
Throws:
IllegalElementException - thrown if the argument points to an illegal index less than 0 or greater than the current size of the arraylist.

removeRange

public final void removeRange(int from,
                              int to)
Removes the elements whose index is between from (inclusive) and to(exclusive). from must be less than to with one exception: if from is equal to to then the method has no effect.

Parameters:
from - starting point for removal (inclusive)
to - end point for removal (exclusive)

remove

public final int remove(int index)
Removes the element at the specified position. The elements that follow the removed element are moved one position forward in the arraylist. The size of the arraylist will be one less after invoking this method.

Parameters:
index - position of the element that should be removed.
Returns:
the element that was just removed from the arraylist.
Throws:
com.tensegrity.generic.util.IllegalElementException - thrown if the index is not pointing to an element in the arraylist.

clear

public final void clear()
Removes all elements from the arraylist.


clone

public java.lang.Object clone()
Makes a shallow copy of arraylist. That means that the elements are not copied, but only their references. Note: If this particular ArrayList happens to store java primitive types like int or long, then a shallow and a deep copy are the same thing.

Overrides:
clone in class java.lang.Object
Returns:
a (shallow) copy of this arraylist.

toArray

public final int[] toArray()
Allocates an array whose length is equal to the size() of this arraylist and then copies the contents of the arraylist into it.

Returns:
the newly allocated array with a copy of the contents of this arraylist.

toArray

public final int[] toArray(int[] dest)
This copies the elements from this array to the passed array-reference. If the argument is an array that is large enough to hold all of the elements of this arraylist then the contents of this arraylist are copied into it and the passed array is also the one being returned to the caller. If the argument is null then a new array as large as the size of the arraylist is allocatted, filled with the elements and then returned. If the destination array is not at least as large as this arraylist then a new array is allocated, filled and returned to the caller. The copy that is made is shallow if Object or subtype is the element type of the array. Otherwise in case primitive types are stored in the array, it doesn't make sense to make a difference between shallow and deep copies anyhow.

Parameters:
dest - the array to copy the contents into if possible.
Returns:
the potentially allocated array with a copy of the contents of this arraylist or the passed in array if it was large enough.

toString

public java.lang.String toString()
Returns a string-representation of the array.

Overrides:
toString in class java.lang.Object
Returns:
array contents concatenated into a string

sort

public final void sort()
Sorts the array in ascending order using quicksort. Worst case time complexity is O(n^2). Overall quicksort is the fastest sorting for random data though. The partioning strategy used is plain halfway partitioning.


sort

public final void sort(boolean descending)
Sorts the array in ascending or descending order using quicksort. Worst case time complexity is O(n^2). Overall quicksort is the fastest sorting for random data though. The partioning strategy used is plain halfway partitioning.

Parameters:
descending - flag that determines the sorting order. If set to true, then the sorting will be done in descending order.

binarySearch

public final int binarySearch(int element)
Performs a binary search on the array. For this to work the array MUST BE SORTED IN ASCENDING ORDER. If this is not the case then the result of the binary search is not defined. If the target element is in the arraylist multiple times, then it is undefined which one is found. The method returns -1 if the element is not found.

Parameters:
element - the element to search for
Returns:
index of any occurence of the element in the arraylist or -1 if the element was not found.

replaceAll

public final boolean replaceAll(int element,
                                int newElement)
Replaces all occurences of element by newElement.

Parameters:
element - the element to replace.
newElement - the replacement for the old element.
Returns:
true if one or more elements were replaced.

reverse

public final void reverse()
Reverses the order of the arraylist.


iterator

public final ArrayListInt.Iterator iterator()
Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this:
 ArrayListInt.Iterator it = alist.iterator();
 while (it.hasNext()) {
   int l = li.previous ();
   System.out.println (" : " + l);
 }
 
For backwards iteration @see ListIterator.

Returns:
a forward iterator for this arraylist.

listIterator

public final ArrayListInt.ListIterator listIterator()
Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this:
 ArrayListInt.ListIterator it = alist.listIterator();
 while (it.hasNext()) {
   int l = li.next ();
   System.out.println (" : " + l);
 }
 
Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious

Returns:
a two-directional iterator for this arraylist.

listIterator

public final ArrayListInt.ListIterator listIterator(int index)
Returns a simple forward iterator with user-specified starting position which can be used to retrieve the contents of the arraylist in reverse order like this:
 ArrayListInt.ListIterator it = alist.listIterator(alist.size());
 while (it.hasPrevious()) {
   int l = li.previous ();
   System.out.println (" : " + l);
 }
 
Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious

Parameters:
index - the initial position of the iterator.
Returns:
a two-directional iterator for this arraylist.
Throws:
com.tensegrity.generic.util.IllegalElementException - thrown if the index is not pointing to an element in the arraylist.