Top Description Fields Constructors Methods
org.python.core

public abstract Class AbstractArray

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Known Direct Subclasses
org.python.core.PyArray.ArrayDelegate
Imports
java.io.Serializable, java.lang.reflect.Array, java.util.Arrays
Abstract class that manages bulk structural and data operations on arrays, defering type-specific element-wise operations to the subclass. Subclasses supply the underlying array and the type-specific operations--greatly reducing the need for casting (thus achieving array-like performances with collection-like flexibility). Also includes functionality to support integration with the the jdk's collections (via methods that return a modification increment).

Subclasses will want to provide the following methods (which are not declared in this class since subclasses should specify the explicit return type):

Clone cannot be supported since the array is not held locally. But the @link #AbstractArray(AbstractArray) constructor can be used for suclasses that need to support clone.

This "type-specific collections" approach was originally developed by Dennis Sosnoski, who provides a more complete library at the referenced URL. Sosnoski's library does not integrate with the jdk collection classes but provides collection-like classes.

Author
Clark Updike
See Also
Sosnoski's Type-Specific Collection Library

Field Summary

Modifier and TypeField and Description
protected int
capacity

Size of the current array, which can be larger than the size field.

protected int
modCountIncr

The modification count increment indicates if a structural change occurred as a result of an operation that would make concurrent iteration over the array invalid.

protected int
size

The number of values currently present in the array.

Constructor Summary

AccessConstructor and Description
public
AbstractArray(AbstractArray toCopy)

Since AbstractArray can support a clone method, this facilitates subclasses that want to implement clone (poor man's cloning).

public
AbstractArray(int
the initial size of the array
size)

Use when the subclass has a preexisting array.

public
AbstractArray(Class<T>
array element type (primitive type or object class)
type)

Creates the managed array with a default size of 10.

public
AbstractArray(Class<T>
Array element type (primitive type or object class).
type, int[]
An int array specifying the dimensions. For a 2D array, something like new int[] {10,0} to create 10 elements each of which can hold an reference to an array of the same type.
dimensions)

Construtor for multi-dimensional array types.

public
AbstractArray(Class<T>
array element type (primitive type or object class)
type, int
number of elements initially allowed in array
size)

Creates the managed array with the specified size.

Method Summary

Modifier and TypeMethod and Description
public void
appendArray(Object
the array to append
ofArrayType)

Appends the supplied array, which must be an array of the same type as this, to the end of this.

public void
clear()

Set the array to the empty state, clearing all the data out and nulling objects (or "zero-ing" primitives).

protected void
clearRange(int
the start index, inclusive
start, int
the stop index, exclusive
stop)

Clears out the values in the specified range.

private void
clearRangeInternal(int
the start index, inclusive
start, int
the stop index, exclusive
stop)

Used internally, no bounds checking.

public Object

Returns:

array containing a shallow copy of the data.
copyArray()

Constructs and returns a simple array containing the same data as held in this growable array.

protected abstract Object

Returns:

an array of the given size for the type used by this abstract array.
createArray(int size)

protected void
ensureCapacity(int
new minimum size required
minCapacity)

Ensures that the base array has at least the specified minimum capacity.

protected int

Returns:

index position for next added element
getAddIndex()

Gets the next add position for appending a value to those in the array.

protected abstract Object

Returns:

backing array object
getArray()

Get the backing array.

public int

Returns:

the modification count increment (0 if no change, 1 if changed)
getModCountIncr()

Returns the modification count increment, which is used by AbstractList subclasses to adjust modCount AbstractList uses it's modCount field to invalidate concurrent operations (like iteration) that should fail if the underlying array changes structurally during the operation.

public int

Returns:

count of values present
getSize()

Get the number of values currently present in the array.

protected boolean
isEmpty()

protected void
makeInsertSpace(int
index position at which to insert element
index)

Makes room to insert a value at a specified index in the array.

protected void
makeInsertSpace(int index, int length)

public void
remove(int
index number of value to be removed
index)

Remove a value from the array.

public void
remove(int
inclusive
start, int
exclusive
stop)

Removes a range from the array at the specified indices.

public void
replaceSubArray(Object array, int atIndex)

Allows an array type to overwrite a segment of the array.

public void
replaceSubArray(int
the start index (inclusive) of the subarray in this array to be replaced
thisStart, int
the stop index (exclusive) of the subarray in this array to be replaced
thisStop, Object
the source array from which to copy
srcArray, int
the start index (inclusive) of the replacement subarray
srcStart, int
the stop index (exclusive) of the replacement subarray
srcStop)

Replace a range of this array with another subarray.

protected abstract void
setArray(Object
the backing array object
array)

Set the backing array.

private void
setNewBase(int newCapacity)

Replaces the existing base array in the subclass with a new base array resized to the specified capacity.

public void
setSize(int
number of values to be set
count)

Sets the number of values currently present in the array.

public String
toString()

Overrides java.lang.Object.toString.

Provides a default comma-delimited representation of array.

protected void
trimToSize()

Removes any excess capacity in the backing array so it is just big enough to hold the amount of data actually in the array.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

capacityback to summary
protected int capacity

Size of the current array, which can be larger than the size field.

modCountIncrback to summary
protected int modCountIncr

The modification count increment indicates if a structural change occurred as a result of an operation that would make concurrent iteration over the array invalid. It is typically used by subclasses that extend AbstractList, by adding the value to AbstractList.modCount after performing a potentially structure-altering operation. A value of 0 indicates that it is still valid to iterate over the array. A value of 1 indicates it is no longer valid to iterate over the range.

This class uses a somewhat stricter semantic for modCount. Namely, modCountIncr is only set to 1 if a structural change occurred. The jdk collections generally increment modCount if a potentially structure-altering method is called, regardless of whether or not a change actually occurred. See also: java.util.AbstractList#modCount

sizeback to summary
protected int size

The number of values currently present in the array.

Constructor Detail

AbstractArrayback to summary
public AbstractArray(AbstractArray toCopy)

Since AbstractArray can support a clone method, this facilitates subclasses that want to implement clone (poor man's cloning). Subclasses can then do this: 

public MyManagedArray(MyManagedArray toCopy) {
    super(this);
    this.baseArray = (<my array type>) toCopy.copyArray();
    this.someProp = toCopy.someProp;
    <etc>
}

public Object clone() {
    return new MyManagedArray(this);
}
AbstractArrayback to summary
public AbstractArray(int size)

Use when the subclass has a preexisting array.

Parameters
size:int

the initial size of the array

AbstractArrayback to summary
public AbstractArray(Class<T> type)

Creates the managed array with a default size of 10.

Parameters
type:Class<T>

array element type (primitive type or object class)

AbstractArrayback to summary
public AbstractArray(Class<T> type, int[] dimensions)

Construtor for multi-dimensional array types. For example, char[][]. This class only manages the top level dimension of the array. For single dimension arrays (the more typical usage), use the other constructors.

Parameters
type:Class<T>

Array element type (primitive type or object class).

dimensions:int[]

An int array specifying the dimensions. For a 2D array, something like new int[] {10,0} to create 10 elements each of which can hold an reference to an array of the same type.

See Also
Array#newInstance(java.lang.Class, int[])
AbstractArrayback to summary
public AbstractArray(Class<T> type, int size)

Creates the managed array with the specified size.

Parameters
type:Class<T>

array element type (primitive type or object class)

size:int

number of elements initially allowed in array

Method Detail

appendArrayback to summary
public void appendArray(Object ofArrayType)

Appends the supplied array, which must be an array of the same type as this, to the end of this.

AbstractList subclasses should update their modCount after calling this method.

Parameters
ofArrayType:Object

the array to append

clearback to summary
public void clear()

Set the array to the empty state, clearing all the data out and nulling objects (or "zero-ing" primitives).

Note

This method does not set modCountIncr to 1 even though java.util.ArrayList would.

AbstractList subclasses should update their modCount after calling this method.

clearRangeback to summary
protected void clearRange(int start, int stop)

Clears out the values in the specified range. For object arrays, the cleared range is nullified. For primitve arrays, it is "zero-ed" out.

Note

This method does not set modCountIncr to 1 even though java.util.ArrayList would.

Parameters
start:int

the start index, inclusive

stop:int

the stop index, exclusive

clearRangeInternalback to summary
private void clearRangeInternal(int start, int stop)

Used internally, no bounds checking.

Parameters
start:int

the start index, inclusive

stop:int

the stop index, exclusive

copyArrayback to summary
public Object copyArray()

Constructs and returns a simple array containing the same data as held in this growable array.

Returns:Object

array containing a shallow copy of the data.

createArrayback to summary
protected abstract Object createArray(int size)
Returns:Object

an array of the given size for the type used by this abstract array.

ensureCapacityback to summary
protected void ensureCapacity(int minCapacity)

Ensures that the base array has at least the specified minimum capacity.

AbstractList subclasses should update their modCount after calling this method.

Parameters
minCapacity:int

new minimum size required

getAddIndexback to summary
protected int getAddIndex()

Gets the next add position for appending a value to those in the array. If the underlying array is full, it is grown by the appropriate size increment so that the index value returned is always valid for the array in use by the time of the return.

AbstractList subclasses should update their modCount after calling this method.

Returns:int

index position for next added element

getArrayback to summary
protected abstract Object getArray()

Get the backing array. This method is used by the type-agnostic base class code to access the array used for type-specific storage by the child class.

Returns:Object

backing array object

getModCountIncrback to summary
public int getModCountIncr()

Returns the modification count increment, which is used by AbstractList subclasses to adjust modCount AbstractList uses it's modCount field to invalidate concurrent operations (like iteration) that should fail if the underlying array changes structurally during the operation.

Returns:int

the modification count increment (0 if no change, 1 if changed)

getSizeback to summary
public int getSize()

Get the number of values currently present in the array.

Returns:int

count of values present

isEmptyback to summary
protected boolean isEmpty()
makeInsertSpaceback to summary
protected void makeInsertSpace(int index)

Makes room to insert a value at a specified index in the array.

AbstractList subclasses should update their modCount after calling this method. Does not change the size property of the array.

Parameters
index:int

index position at which to insert element

makeInsertSpaceback to summary
protected void makeInsertSpace(int index, int length)
removeback to summary
public void remove(int index)

Remove a value from the array. All values above the index removed are moved down one index position.

AbstractList subclasses should always increment their modCount method after calling this, as remove always causes a structural modification.

Parameters
index:int

index number of value to be removed

removeback to summary
public void remove(int start, int stop)

Removes a range from the array at the specified indices.

Parameters
start:int

inclusive

stop:int

exclusive

replaceSubArrayback to summary
public void replaceSubArray(Object array, int atIndex)

Allows an array type to overwrite a segment of the array. Will expand the array if (atIndex + 1) + ofArrayType's length is greater than the current length.

AbstractList subclasses should update their modCount after calling this method.

replaceSubArrayback to summary
public void replaceSubArray(int thisStart, int thisStop, Object srcArray, int srcStart, int srcStop)

Replace a range of this array with another subarray.

Parameters
thisStart:int

the start index (inclusive) of the subarray in this array to be replaced

thisStop:int

the stop index (exclusive) of the subarray in this array to be replaced

srcArray:Object

the source array from which to copy

srcStart:int

the start index (inclusive) of the replacement subarray

srcStop:int

the stop index (exclusive) of the replacement subarray

setArrayback to summary
protected abstract void setArray(Object array)

Set the backing array. This method is used by the type-agnostic base class code to set the array used for type-specific storage by the child class.

Parameters
array:Object

the backing array object

setNewBaseback to summary
private void setNewBase(int newCapacity)

Replaces the existing base array in the subclass with a new base array resized to the specified capacity.

setSizeback to summary
public void setSize(int count)

Sets the number of values currently present in the array. If the new size is greater than the current size, the added values are initialized to the default values. If the new size is less than the current size, all values dropped from the array are discarded.

AbstractList subclasses should update their modCount after calling this method.

Parameters
count:int

number of values to be set

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Provides a default comma-delimited representation of array.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

Annotations
@Override
See Also
java.lang.Object#toString()

trimToSizeback to summary
protected void trimToSize()

Removes any excess capacity in the backing array so it is just big enough to hold the amount of data actually in the array.