ch.javasoft.util
Class LongArray

java.lang.Object
  ch.javasoft.util.LongArray

All Implemented Interfaces:

Serializable, Cloneable, Iterable<Long>

public class LongArray
extends Object
implements Iterable<Long>, Cloneable, Serializable

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

See Also:

Serialized Form

Constructor Summary

LongArray()
Constructor for LongArray with default capacity

LongArray(int capacity)
Constructor for LongArray with default capacity

LongArray(long[] initialValues)
Constructor for LongArray with specified values.

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

Method Summary

boolean	add(int index, long value) Adds the specified value at the given position of the array.
void	add(long value) Adds the specified value to the end of this long array
void	addAll(int from, int to, long... values) Adds the specified values to the end of this long array
void	addAll(int from, int to, LongArray array) Adds the values from array to the end of this int array
void	addAll(long... values) Adds the specified values to the end of this long array
void	addAll(LongArray array) Adds the values from array to the end of this long array
int	addToSorted(long value) Adds the given value at the position where the value fits according to binarySearch(long).
int	binarySearch(long key) Searches this int array for the specified value using the binary search algorithm.
int	binarySearch(long 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).
LongArray	clone() Returns a clone of this long array
static long[][]	clone(long[][] 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)
long	first() Returns the first element, or throws an IndexOutOfBoundsException if the array is empty
long	get(int index) Returns the value at the specified position
int	hashCode()
int	indexOf(int fromIndex, long value) Returns the first index containing a value equal to the specified value starting at position fromIndex.
int	indexOf(long value) Returns the first index containing a value equal to the specified value.
protected long	initialValue() This method can be overriden to define an alternate initial value.
boolean	isEmpty() Returns true if the array length is zero
Iterator<Long>	iterator() Returns an immutable iterator with the long values of this array
long	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.
long	remove(int index) Removes the specified value and moves all values on the right one position leftwards.
long	removeLast() Removes the last value, or throws an IndexOutOfBoundsException if the array is empty.
long	set(int index, long 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.
LongArray	subRange(int from) Returns a new array instance containing a copy of a range of this array.
LongArray	subRange(int from, int to) Returns a new array instance containing a copy of a range of this array.
void	swap(int indexA, int indexB) Interchange the values at the specified positions
static void	swap(long[] arr, int indexA, int indexB) Interchange the values at the specified array positions
long[]	toArray() Clones the underlying array (trimmed to length) and returns it
static long[][]	toMatrix(Collection<long[]> mx, boolean cloneArrays) Converts the given collection of long arrays to a two dimensional long array.
static long[][]	toMatrix(Collection<LongArray> mx) Converts the given collection of LongArray instances to a two dimensional long array
static long[][]	toMatrix(LongArray[] mx) Converts the given array of LongArray instances to a two dimensional long 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.
long[]	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

LongArray

public LongArray()

Constructor for LongArray with default capacity

LongArray

public LongArray(int capacity)

Constructor for LongArray with default capacity

LongArray

public LongArray(long[] initialValues)

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

LongArray

public LongArray(long[] original,
                 int from,
                 int to)

Constructor for LongArray 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 long get(int index)
         throws IndexOutOfBoundsException

Returns the value at the specified position

Throws:

IndexOutOfBoundsException

indexOf

public int indexOf(long 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,
                   long 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 long set(int index,
                long 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(long value)

Adds the specified value to the end of this long array

addAll

public void addAll(LongArray array)

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

addAll

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

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

addAll

public void addAll(long... values)

Adds the specified values to the end of this long array

addAll

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

Adds the specified values to the end of this long array

add

public boolean add(int index,
                   long 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 long removeLast()

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

remove

public long 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 long first()

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

last

public long 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 long initialValue()

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

Default initial value is 0

toArray

public long[] toArray()

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

Returns:

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

yieldArray

public long[] yieldArray()

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

clone

public LongArray clone()

Returns a clone of this long array

Overrides:

clone in class Object

subRange

public LongArray 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 LongArray 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<Long> iterator()

Returns an immutable iterator with the long values of this array

Specified by:

iterator in interface Iterable<Long>

toMatrix

public static long[][] toMatrix(LongArray[] mx)

Converts the given array of LongArray instances to a two dimensional long array

Parameters:

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

Returns:

the two dimensional array

toMatrix

public static long[][] toMatrix(Collection<LongArray> mx)

Converts the given collection of LongArray instances to a two dimensional long array

Parameters:

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

Returns:

the two dimensional array

toMatrix

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

Converts the given collection of long arrays to a two dimensional long 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(long[] arr,
                        int indexA,
                        int indexB)

Interchange the values at the specified array positions

clone

public static long[][] clone(long[][] 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(long 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(long 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(long value)

Adds the given value at the position where the value fits according to binarySearch(long). 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(long) and addToSorted(long) 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(long) and addToSorted(long) 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(long).

Overrides:

toString in class Object

Returns:

a string representation of this array

See Also:

Arrays.toString(long[])