net.walend.grid
Class AbstractMapGrid2D

java.lang.Object
  |
  +--net.walend.grid.AbstractMapGrid2D

All Implemented Interfaces:

java.util.Collection, Grid, Grid2D, HasState, java.io.Serializable

Direct Known Subclasses:

MapGrid2D, MutableMapGrid2D

public abstract class AbstractMapGrid2D

extends java.lang.Object

implements Grid2D, java.io.Serializable

Grid2D is a simple two-dimensional Grid built atop a Map. Use MapGrids when many of the Grid's addresses have the same value.

Author:

David Walend dfw1@cornell.edu

See Also:

Serialized Form

Nested Class Summary

private class	AbstractMapGrid2D.AddressIterator
private class	AbstractMapGrid2D.IStripeIterator
private class	AbstractMapGrid2D.JStripeIterator
private class	AbstractMapGrid2D.WholeGridIterator

Nested classes inherited from class net.walend.grid.Grid2D

Grid2D.Dimensions2D

Field Summary

private static int	DEFAULTMAPSIZE
private java.lang.Object	fill
private java.util.Map	map
private Address2D	maxAddress

Fields inherited from interface net.walend.grid.Grid2D

DIMENSIONS2D, I, J

Constructor Summary

protected	AbstractMapGrid2D(Address2D maxAddress)
protected	AbstractMapGrid2D(Address2D maxAddress, Grid2D grid)
protected	AbstractMapGrid2D(Address2D maxAddress, java.lang.Object fill)
protected	AbstractMapGrid2D(Grid2D grid)
protected	AbstractMapGrid2D(int sizeI, int sizeJ)
protected	AbstractMapGrid2D(int sizeI, int sizeJ, Grid2D grid)
protected	AbstractMapGrid2D(int sizeI, int sizeJ, java.lang.Object fill)
protected	AbstractMapGrid2D(int sizeI, int sizeJ, java.lang.Object fill, int mapSize)

Method Summary

boolean	add(java.lang.Object o) Throws an UnsupportedOperationException.
boolean	addAll(java.util.Collection c) Throws an UnsupportedOperationException.
java.util.Iterator	addressIterator() Returns an Iterator of all the addresses in the grid.
Address	addressOf(java.lang.Object object) Returns an Address in the Grid occupied by object.
private static Address2D	castAddress(Address address)
protected void	checkAddress(int i, int j)
void	clear() Replaces all of the elements with fill.
boolean	contains(java.lang.Object o) Returns true if this collection contains the specified element.
boolean	containsAddress(Address address) Returns true if the address is on this Grid.
boolean	containsAddress(int i, int j) Return true if the i,j address is on the Grid.
boolean	containsAll(java.util.Collection c) Returns true if this collection contains all of the elements in the specified collection.
boolean	containsDimension(Dimension dimension) Returns true if dimension is used in this Grid.
java.lang.Object	get(Address address) Return the Object at address.
java.lang.Object	get(int i, int j) Returns the object in the grid at i,j.
net.walend.enum.Enum	getDimensions() Returns the Dimensions enumerated type
java.lang.Object	getFillObject() Return the fill object for this grid.
java.lang.Class	getPrincipleInterface() Returns the class's principle interface for state comparisons, net.walend.grid.Grid2D.
private void	init(int sizeI, int sizeJ, java.lang.Object fill, int mapSize)
boolean	isEmpty() Returns true if this collection contains no elements.
IndexedIterator	iStripeIterator(int i) Returns an iterator accross zs at i.
java.util.Iterator	iterator() Returns an iterator over the elements in this collection.
IndexedIterator	jStripeIterator(int j) Returns an iterator accross is at j.
Address	maxAddress() Return the address furthest from the origin for this grid.
protected java.lang.Object	put(Address address, java.lang.Object object) Replace the Object at address with object.
protected java.lang.Object	put(int i, int j, java.lang.Object object) Replaces the object at i,j with object.
boolean	remove(java.lang.Object o) Removes a single instance of the specified element from this collection, if it is present (optional operation).
boolean	removeAll(java.util.Collection c) Removes all this collection's elements that are also contained in the specified collection (optional operation).
boolean	retainAll(java.util.Collection c) Retains only the elements in this collection that are contained in the specified collection (optional operation).
boolean	sameGrid2DAs(Grid2D grid) If this has the same contents as grid in the same spots, returns true.
boolean	sameStateAs(HasState victim) If two HasStates have the same internal state, return true.
int	size() Returns the number of elements in this collection.
int	sizeI() Return the size of the grid in I.
int	sizeJ() Return the size of the grid in J.
IndexedIterator	stripeIterator(Address address, Dimension dimensionToScan) Returns an Iterator accross the stripe at Address, through dimensionToScan.
protected java.lang.Object	take(Address address) Replace the Object at Address with fill.
protected java.lang.Object	take(int i, int j) Replaces the object at i,j with fill.
java.lang.Object[]	toArray() Returns an array containing all of the elements in this collection.
java.lang.Object[]	toArray(java.lang.Object[] a) Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, hashCode

Field Detail

map

private java.util.Map map

fill

private java.lang.Object fill

maxAddress

private Address2D maxAddress

DEFAULTMAPSIZE

private static final int DEFAULTMAPSIZE

See Also:

Constant Field Values

Constructor Detail

AbstractMapGrid2D

protected AbstractMapGrid2D(int sizeI,
                            int sizeJ,
                            java.lang.Object fill,
                            int mapSize)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(int sizeI,
                            int sizeJ,
                            java.lang.Object fill)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(int sizeI,
                            int sizeJ)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(Address2D maxAddress)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(Address2D maxAddress,
                            java.lang.Object fill)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(Grid2D grid)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(Address2D maxAddress,
                            Grid2D grid)
                     throws OffGridException

AbstractMapGrid2D

protected AbstractMapGrid2D(int sizeI,
                            int sizeJ,
                            Grid2D grid)
                     throws OffGridException

Method Detail

init

private void init(int sizeI,
                  int sizeJ,
                  java.lang.Object fill,
                  int mapSize)
           throws OffGridException

OffGridException

castAddress

private static Address2D castAddress(Address address)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getPrincipleInterface

public java.lang.Class getPrincipleInterface()

Returns the class's principle interface for state comparisons, net.walend.grid.Grid2D. If two objects have different principle interfaces, they never have the same state.

Specified by:

getPrincipleInterface in interface HasState

sameStateAs

public boolean sameStateAs(HasState victim)

If two HasStates have the same internal state, return true.

For objects with subobjects, Generally this method should only return true if the internal objects are equal. Implement a contentsHaveSameState() method to determine if the contents have the same state.

Specified by:

sameStateAs in interface HasState

size

public int size()

Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

I've decided to count nulls as elements in Grids, so this returns sizeI()*sizeJ().

Specified by:

size in interface java.util.Collection

Returns:

the number of elements in this collection

isEmpty

public boolean isEmpty()

Returns true if this collection contains no elements.

Since nulls count as values, this method would only return true for a Grid with no elements.

Specified by:

isEmpty in interface java.util.Collection

Returns:

true if this collection contains no elements

contains

public boolean contains(java.lang.Object o)

Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)).

This method scans the entire map before returning false.

Specified by:

contains in interface java.util.Collection

Parameters:

o - element whose presence in this collection is to be tested.

Returns:

true if this collection contains the specified element

iterator

public java.util.Iterator iterator()

Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned.

Specified by:

iterator in interface java.util.Collection

Returns:

an Iterator over the elements in this collection

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Specified by:

toArray in interface java.util.Collection

Returns:

an array containing all of the elements in this collection

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)

Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

Like the toArray method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs

Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String:

    String[] x = (String[]) v.toArray(new String[0]);

Note that toArray(new Object[0]) is identical in function to toArray().

Specified by:

toArray in interface java.util.Collection

Parameters:

a - the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of this collection

Throws:

java.lang.ArrayStoreException - the runtime type of the specified array is not a supertype of the runtime type of every element in this collection.

add

public boolean add(java.lang.Object o)

Throws an UnsupportedOperationException.

Specified by:

add in interface java.util.Collection

remove

public boolean remove(java.lang.Object o)

Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

This method has to scan the array to find the element to remove.

Removing the fill object always returns false. Either the Grid doesn't contain the object, or removing one (replacing it with the fill object) won't change the Grid.

Specified by:

remove in interface java.util.Collection

Parameters:

o - element to be removed from this collection, if present.

Returns:

true if this collection changed as a result of the call

containsAll

public boolean containsAll(java.util.Collection c)

Returns true if this collection contains all of the elements in the specified collection.

Specified by:

containsAll in interface java.util.Collection

Parameters:

c - collection to be checked for containment in this collection.

Returns:

true if this collection contains all of the elements in the specified collection

See Also:

contains(Object)

addAll

public boolean addAll(java.util.Collection c)

Throws an UnsupportedOperationException.

Specified by:

addAll in interface java.util.Collection

removeAll

public boolean removeAll(java.util.Collection c)

Removes all this collection's elements that are also contained in the specified collection (optional operation). After this call returns, this collection will contain no elements in common with the specified collection, unless that collection contained the fill object.

Because this method replaces every object it removes with the fill object, putting the fill object in the collection won't get rid of it.

Specified by:

removeAll in interface java.util.Collection

Parameters:

c - elements to be removed from this collection.

Returns:

true if this collection changed as a result of the call

Throws:

java.lang.UnsupportedOperationException - if the removeAll method is not supported by this collection.

See Also:

remove(Object), contains(Object)

retainAll

public boolean retainAll(java.util.Collection c)

Retains only the elements in this collection that are contained in the specified collection (optional operation). In other words, removes from this collection all of its elements that are not contained in the specified collection, except for the fill object.

Because this method replaces every object it removes with the fill object, leaving the fill object out of the collection won't get rid of it.

Specified by:

retainAll in interface java.util.Collection

Parameters:

c - elements to be retained in this collection.

Returns:

true if this collection changed as a result of the call

Throws:

java.lang.UnsupportedOperationException - if the retainAll method is not supported by this Collection.

See Also:

remove(Object), contains(Object)

clear

public void clear()

Replaces all of the elements with fill. Removes all of the elements from this collection (optional operation). This collection will be empty after this method returns unless it throws an exception.

Specified by:

clear in interface java.util.Collection

Throws:

java.lang.UnsupportedOperationException - if the clear method is not supported by this collection.

getFillObject

public java.lang.Object getFillObject()

Return the fill object for this grid.

Specified by:

getFillObject in interface Grid

containsDimension

public boolean containsDimension(Dimension dimension)

Returns true if dimension is used in this Grid.

Specified by:

containsDimension in interface Grid

getDimensions

public net.walend.enum.Enum getDimensions()

Returns the Dimensions enumerated type

Specified by:

getDimensions in interface Grid

maxAddress

public Address maxAddress()

Return the address furthest from the origin for this grid. You can use this address as the maximum value in for loops safly, provided your grid doesn't have arbitrary holes in it.

Specified by:

maxAddress in interface Grid

containsAddress

public boolean containsAddress(Address address)

Returns true if the address is on this Grid.

Specified by:

containsAddress in interface Grid

get

public java.lang.Object get(Address address)
                     throws OffGridException

Return the Object at address.

Specified by:

get in interface Grid

OffGridException

addressOf

public Address addressOf(java.lang.Object object)
                  throws ObjectNotOnGridException

Returns an Address in the Grid occupied by object.

Specified by:

addressOf in interface Grid

ObjectNotOnGridException

put

protected java.lang.Object put(Address address,
                               java.lang.Object object)
                        throws OffGridException

Replace the Object at address with object.

Returns:

the Object that was at Address.

OffGridException

take

protected java.lang.Object take(Address address)
                         throws OffGridException

Replace the Object at Address with fill.

Returns:

the Object that was at Address.

OffGridException

stripeIterator

public IndexedIterator stripeIterator(Address address,
                                      Dimension dimensionToScan)

Returns an Iterator accross the stripe at Address, through dimensionToScan. This iterator is remarkably robust and will not throw ConcurrentModificationExceptions.

Specified by:

stripeIterator in interface Grid

sizeI

public int sizeI()

Return the size of the grid in I.

Specified by:

sizeI in interface Grid2D

sizeJ

public int sizeJ()

Return the size of the grid in J.

Specified by:

sizeJ in interface Grid2D

containsAddress

public boolean containsAddress(int i,
                               int j)

Return true if the i,j address is on the Grid.

Specified by:

containsAddress in interface Grid2D

checkAddress

protected void checkAddress(int i,
                            int j)

get

public java.lang.Object get(int i,
                            int j)
                     throws OffGridException

Returns the object in the grid at i,j.

Specified by:

get in interface Grid2D

OffGridException

take

protected java.lang.Object take(int i,
                                int j)
                         throws OffGridException

Replaces the object at i,j with fill.

Returns:

the object that was at i,j.

OffGridException

put

protected java.lang.Object put(int i,
                               int j,
                               java.lang.Object object)

Replaces the object at i,j with object.

Returns:

the object that was at i,j.

sameGrid2DAs

public boolean sameGrid2DAs(Grid2D grid)

If this has the same contents as grid in the same spots, returns true. Ignores the fill object.

Specified by:

sameGrid2DAs in interface Grid2D

iStripeIterator

public IndexedIterator iStripeIterator(int i)
                                throws OffGridException

Returns an iterator accross zs at i.

Specified by:

iStripeIterator in interface Grid2D

OffGridException

jStripeIterator

public IndexedIterator jStripeIterator(int j)
                                throws OffGridException

Returns an iterator accross is at j.

Specified by:

jStripeIterator in interface Grid2D

OffGridException

addressIterator

public java.util.Iterator addressIterator()

Returns an Iterator of all the addresses in the grid.

Specified by:

addressIterator in interface Grid