ch.javasoft.util
Class IntArray

java.lang.Object
  ch.javasoft.util.IntArray

All Implemented Interfaces:

Serializable, Cloneable, Iterable<Integer>

public class IntArray
extends Object
implements Iterable<Integer>, Cloneable, Serializable

The IntArray is an dynamic size array for ints. Values can be added causing the array to grow dynamically.

See Also:

Serialized Form

Constructor Summary

IntArray()
Constructor for IntArray with default capacity

IntArray(int capacity)
Constructor for IntArray with default capacity

IntArray(int[] initialValues)
Constructor for IntArray with specified values.

IntArray(int[] original, int from, int to)
Constructor for IntArray with specified values.

Method Summary

void	add(int value) Adds the specified value to the end of this int array
boolean	add(int index, int value) Adds the specified value at the given position of the array.
void	addAll(int... values) Adds the specified values to the end of this int array
void	addAll(IntArray array) Adds the values from array to the end of this int array
void	addAll(int from, int to, int... values) Adds the specified values to the end of this int array, from index from (inclusive) to to (exclusive).
void	addAll(int from, int to, IntArray array) Adds the values from array to the end of this int array
int	addToSorted(int value) Adds the given value at the position where the value fits according to binarySearch(int).
int	binarySearch(int key) Searches this int array for the specified value using the binary search algorithm.
int	binarySearch(int key, int fromIndex, int toIndex) Searches this int array for the specified value using the binary search algorithm.
void	clear() Removes all elements, but does not shrink the underlying array (that is, the capacity is kept as it is).
IntArray	clone() Returns a clone of this int array
static int[][]	clone(int[][] arr) Returns a deep clone of the given array
protected void	ensureCapacity(int size) Internal method, called to ensure capacity size
boolean	equals(Object obj)
int	first() Returns the first element, or throws an IndexOutOfBoundsException if the array is empty
int	get(int index) Returns the value at the specified position
int	hashCode()
int	indexOf(int value) Returns the first index containing a value equal to the specified value.
int	indexOf(int fromIndex, int value) Returns the first index containing a value equal to the specified value starting at position fromIndex.
protected int	initialValue() This method can be overriden to define an alternate initial value.
boolean	isEmpty() Returns true if the array length is zero
Iterator<Integer>	iterator() Returns an immutable iterator with the integer values of this array
int	last() Returns the last element, or throws an IndexOutOfBoundsException if the array is empty
int	length() Returns the current length of this array, that is, the number of elements in the array.
int	remove(int index) Removes the specified value and moves all values on the right one position leftwards.
int	removeLast() Removes the last value, or throws an IndexOutOfBoundsException if the array is empty.
int	set(int index, int value) Sets the value at the specified position.
void	sort(boolean ascending) Sort the array ascending or descending.
void	sort(boolean ascending, int start, int end) Sort the specified array range ascending or descending.
IntArray	subRange(int from) Returns a new array instance containing a copy of a range of this array.
IntArray	subRange(int from, int to) Returns a new array instance containing a copy of a range of this array.
static void	swap(int[] arr, int indexA, int indexB) Interchange the values at the specified array positions
void	swap(int indexA, int indexB) Interchange the values at the specified positions
int[]	toArray() Clones the underlying array (trimmed to length) and returns it
static int[][]	toMatrix(Collection<int[]> mx, boolean cloneArrays) Converts the given collection of int arrays to a two dimensional int array.
static int[][]	toMatrix(Collection<IntArray> mx) Converts the given collection of IntArray instances to a two dimensional int array
static int[][]	toMatrix(IntArray[] mx) Converts the given array of IntArray instances to a two dimensional int array
String	toString() Returns a string representation of the contents of this array.
void	trimToLength() Fixes the capacity of the underlying array to the current length of this array.
int[]	yieldArray() Returns the internal array after trimming it to the current length and returns it.

Methods inherited from class java.lang.Object

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

Constructor Detail

IntArray

public IntArray()

Constructor for IntArray with default capacity

IntArray

public IntArray(int capacity)

Constructor for IntArray with default capacity

IntArray

public IntArray(int[] initialValues)

Constructor for IntArray with specified values. The given array is not cloned, thus, changes to the array are also reflected in the state this IntArray.

IntArray

public IntArray(int[] original,
                int from,
                int to)

Constructor for IntArray with specified values. The given array is cloned.

Copies the specified range of the specified array into this new array. The initial index of the range (from) must lie between zero and original.length, inclusive. The value at original[from] is placed into the initial element of the copy (unless from == original.length or from == to). Values from subsequent elements in the original array are placed into subsequent elements in the copy. The final index of the range (to), which must be greater than or equal to from, may be greater than original.length, in which case 0d is placed in all elements of the copy whose index is greater than or equal to original.length - from. The length of the this array will be to - from.

Parameters:

original - the array from which a range is to be copied

from - the initial index of the range to be copied, inclusive

to - the final index of the range to be copied, exclusive. (This index may lie outside the array.)

Method Detail

length

public int length()

Returns the current length of this array, that is, the number of elements in the array.

isEmpty

public boolean isEmpty()

Returns true if the array length is zero

get

public int get(int index)
        throws IndexOutOfBoundsException

Returns the value at the specified position

Throws:

IndexOutOfBoundsException

indexOf

public int indexOf(int value)

Returns the first index containing a value equal to the specified value. If no such value is found, -1 is returned.

Parameters:

value - the value to search for

Returns:

the index of the first occurrence of value, or -1 if no such value is found

indexOf

public int indexOf(int fromIndex,
                   int value)

Returns the first index containing a value equal to the specified value starting at position fromIndex. If no such value is found, -1 is returned.

Parameters:

fromIndex - the index (inclusive) at which the search is started

value - the value to search for

Returns:

the index of the first occurrence of value, or -1 if no such value is found

set

public int set(int index,
               int value)
        throws IndexOutOfBoundsException

Sets the value at the specified position. If index is smaller than the current length(), the value at the specified position is replaced by value. If index equal to the length of this array, the value is appended. If it is larger than length, it is also appended after filling the gap positions with initial values.

Parameters:

index - the index at which value will be stored

value - the new value to be set

Throws:

IndexOutOfBoundsException

add

public void add(int value)

Adds the specified value to the end of this int array

addAll

public void addAll(IntArray array)

Adds the values from array to the end of this int array

addAll

public void addAll(int from,
                   int to,
                   IntArray array)

Adds the values from array to the end of this int array

addAll

public void addAll(int... values)

Adds the specified values to the end of this int array

addAll

public void addAll(int from,
                   int to,
                   int... values)

Adds the specified values to the end of this int array, from index from (inclusive) to to (exclusive).

add

public boolean add(int index,
                   int value)

Adds the specified value at the given position of the array. If the index is negative or larger than the current length of this array, an IndexOutOfBoundsException is thrown.

removeLast

public int removeLast()

Removes the last value, or throws an IndexOutOfBoundsException if the array is empty.

remove

public int remove(int index)

Removes the specified value and moves all values on the right one position leftwards.

Throws:

IndexOutOfBoundsException - if index is negative or larger or equal to length

clear

public void clear()

Removes all elements, but does not shrink the underlying array (that is, the capacity is kept as it is).

first

public int first()

Returns the first element, or throws an IndexOutOfBoundsException if the array is empty

last

public int last()

Returns the last element, or throws an IndexOutOfBoundsException if the array is empty

swap

public void swap(int indexA,
                 int indexB)

Interchange the values at the specified positions

ensureCapacity

protected void ensureCapacity(int size)

Internal method, called to ensure capacity size

Parameters:

size - the desired capacity

initialValue

protected int initialValue()

This method can be overriden to define an alternate initial value. The initial value is used if set(int, int) is used with an index larger than the length of the array.

Default initial value is 0

toArray

public int[] toArray()

Clones the underlying array (trimmed to length) and returns it

Returns:

a copy of the underlying array, trimmed to the length of this \ int array

yieldArray

public int[] yieldArray()

Returns the internal array after trimming it to the current length and returns it. This IntArray will be empty after this operation.

clone

public IntArray clone()

Returns a clone of this int array

Overrides:

clone in class Object

subRange

public IntArray subRange(int from)

Returns a new array instance containing a copy of a range of this array. The range starts from from (inclusive) to the end of this array.

Parameters:

from - the start index of the range, inclusive

Returns:

a new array containing a copy of the specified range

subRange

public IntArray subRange(int from,
                         int to)

Returns a new array instance containing a copy of a range of this array. The range starts from from (inclusive) to to (exclusive).

Parameters:

from - the start index of the range, inclusive

to - the end index of the range, exclusive

Returns:

a new array containing a copy of the specified range

iterator

public Iterator<Integer> iterator()

Returns an immutable iterator with the integer values of this array

Specified by:

iterator in interface Iterable<Integer>

toMatrix

public static int[][] toMatrix(IntArray[] mx)

Converts the given array of IntArray instances to a two dimensional int array

Parameters:

mx - the array of IntArray instances to convert to a 2-dim array

Returns:

the two dimensional array

toMatrix

public static int[][] toMatrix(Collection<IntArray> mx)

Converts the given collection of IntArray instances to a two dimensional int array

Parameters:

mx - the collection of arrays to convert to a 2-dim array

Returns:

the two dimensional array

toMatrix

public static int[][] toMatrix(Collection<int[]> mx,
                               boolean cloneArrays)

Converts the given collection of int arrays to a two dimensional int array. The source arrays are cloned upon request.

Parameters:

mx - the collection of arrays to convert to a 2-dim array

cloneArrays - if true, the source arrays are cloned

Returns:

the two dimensional array

swap

public static void swap(int[] arr,
                        int indexA,
                        int indexB)

Interchange the values at the specified array positions

clone

public static int[][] clone(int[][] arr)

Returns a deep clone of the given array

trimToLength

public void trimToLength()

Fixes the capacity of the underlying array to the current length of this array. Note that this operation might be expensive due to array copying.

binarySearch

public int binarySearch(int key)
                 throws IllegalStateException

Searches this int array for the specified value using the binary search algorithm. The array must be sorted ascending (as by the sort(boolean) method) prior to making this call. If it is not sorted, the results are undefined. If the array contains multiple elements with the specified value, there is no guarantee which one will be found.

Parameters:

key - the value to be searched for.

Returns:

index of the search key, if it is contained in the list; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the list: the index of the first element greater than the key, or list.size(), if all elements in the list are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

Throws:

IllegalStateException

See Also:

Arrays.binarySearch(int[], int, int, int)

binarySearch

public int binarySearch(int key,
                        int fromIndex,
                        int toIndex)
                 throws IllegalStateException

Searches this int array for the specified value using the binary search algorithm. The array must be sorted ascending (as by the sort(boolean) method) prior to making this call. If it is not sorted, the results are undefined. If the array contains multiple elements with the specified value, there is no guarantee which one will be found.

Parameters:

key - the value to be searched for.

fromIndex - the index of the first element (inclusive) to be searched

toIndex - the index of the last element (exclusive) to be searched

Returns:

index of the search key, if it is contained in the list; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the list: the index of the first element greater than the key, or list.size(), if all elements in the list are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

Throws:

IllegalStateException

See Also:

Arrays.binarySearch(int[], int, int, int)

addToSorted

public int addToSorted(int value)

Adds the given value at the position where the value fits according to binarySearch(int). If this int array is not sorted ascending, the result is undefined.

Parameters:

value - the value to insert

Returns:

the position where the value has been inserted

sort

public void sort(boolean ascending)

Sort the array ascending or descending. If this array is sorted ascending, the binarySearch(int) and addToSorted(int) methods can be used

Parameters:

ascending - true for ascending sort order

sort

public void sort(boolean ascending,
                 int start,
                 int end)

Sort the specified array range ascending or descending. If this whole array is sorted ascending, the binarySearch(int) and addToSorted(int) methods can be used.

This method should only be used if one knows that only the defined interval needs sorting. Otherwise, sort(boolean) should be used instead.

Parameters:

ascending - true for ascending sort order

start - the index where the sorting starts (inclusive)

end - the index where the sorting ends (exclusive)

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Returns a string representation of the contents of this array. The string representation consists of a list of the array's elements, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (a comma followed by a space). Elements are converted to strings as by String.valueOf(int).

Overrides:

toString in class Object

Returns:

a string representation of this array

See Also:

Arrays.toString(int[])