com.tensegrity.generic.util
Class ArrayListChar

java.lang.Object
  com.tensegrity.generic.util.ArrayListChar

public final class ArrayListChar

extends java.lang.Object

ArrayListChar 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 ArrayListChar.Iterator and ArrayListChar.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: ArrayListChar.java,v 1.26 2004/06/30 11:46:37 sr Exp $

Author:

S.Rutz

Nested Class Summary

class	ArrayListChar.Iterator ArrayListChar.Iterator provides a simple forware iterator with basic versioning.
class	ArrayListChar.ListIterator ArrayListChar.ListIterator is a bidirectional iterator with basic versioning.

Constructor Summary

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

ArrayListChar(char[] array)
Constructs a new arraylist and initializes the elements with the contents from the array passed as argument.

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

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

Method Summary

boolean	add(char element) Appends the element at the end of the arraylist.
void	add(int index, char element) Insert the element into the arraylist at the specified position.
boolean	addAll(ArrayListChar otherlist) Appends all of the elements of another list after the end of this arraylist.
int	binarySearch(char 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(char 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.
char	get(int index) Retrieves the element at the given position in the arraylist.
int	indexOf(char element) Forward search for an element in the arraylist starting at index 0.
boolean	isEmpty() Tests whether this arraylist is empty or not.
ArrayListChar.Iterator	iterator() Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this: ArrayListChar.Iterator it = alist.iterator(); while (it.hasNext()) { char l = li.previous (); System.out.println (" : " + l); } For backwards iteration @see ListIterator.
int	lastIndexOf(char element) Seeks an element backwards from the end of the arraylist.
ArrayListChar.ListIterator	listIterator() Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this: ArrayListChar.ListIterator it = alist.listIterator(); while (it.hasNext()) { char l = li.next (); System.out.println (" : " + l); } Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious
ArrayListChar.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: ArrayListChar.ListIterator it = alist.listIterator(alist.size()); while (it.hasPrevious()) { char l = li.previous (); System.out.println (" : " + l); } Additionally the list iterator is capable of backwards iteration using the methods @see previous and @see hasPrevious
char	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(char element, char newElement) Replaces all occurences of element by newElement.
void	reverse() Reverses the order of the arraylist.
char	set(int index, char 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.
char[]	toArray() Allocates an array whose length is equal to the size() of this arraylist and then copies the contents of the arraylist into it.
char[]	toArray(char[] 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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ArrayListChar

public ArrayListChar(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.

ArrayListChar

public ArrayListChar()

Constructs a new arraylist with a default capacity of 8 elements.

ArrayListChar

public ArrayListChar(int n,
                     char 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

ArrayListChar

public ArrayListChar(char[] 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(char 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(char 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(char 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 char 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 char set(int index,
                      char 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(char 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(ArrayListChar 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,
                      char 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 char 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:

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.

Returns:

a (shallow) copy of this arraylist.

toArray

public final char[] 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 char[] toArray(char[] 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.

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(char 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(char element,
                                char 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 ArrayListChar.Iterator iterator()

Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this:

 ArrayListChar.Iterator it = alist.iterator();
 while (it.hasNext()) {
   char l = li.previous ();
   System.out.println (" : " + l);
 }
 

For backwards iteration @see ListIterator.

Returns:

a forward iterator for this arraylist.

listIterator

public final ArrayListChar.ListIterator listIterator()

Returns a simple forward iterator to the caller which can be used to retrieve the contents of the arraylist like this:

 ArrayListChar.ListIterator it = alist.listIterator();
 while (it.hasNext()) {
   char 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 ArrayListChar.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:

 ArrayListChar.ListIterator it = alist.listIterator(alist.size());
 while (it.hasPrevious()) {
   char 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:

IllegalElementException - thrown if the index is not pointing to an element in the arraylist.