edu.kzoo.grid
Class Grid

java.lang.Object
  |
  +--edu.kzoo.grid.Grid

Direct Known Subclasses:

ArrayListGrid.Bounded, ArrayListGrid.Unbounded, BoundedGrid

public abstract class Grid

extends java.lang.Object

Grid Container Package:
A Grid is a two-dimensional, rectangular container data structure. It can contain any kind of object that can be modeled using an extension of the GridObject class. For example, a grid could be used to model a board for a tic-tac-toe or chess game, an environment of fish for a marine biology simulation, etc.

The Grid class is based on the College Board's Environment interface and SquareEnvironment class, as allowed by the GNU General Public License.

Version:

13 December 2003

Author:

Alyce Brady

See Also:

Direction, Location, GridObject

Nested Class Summary

static class	Grid.BoundedGridValidityChecker A BoundedGridValidityChecker implements a strategy for determining the validity of a location in a bounded grid.
protected static interface	Grid.InternalRepresentation The InternalRepresentation interface specifies the methods that any internal representation of the Grid class must implement.
static class	Grid.UnboundedGridValidityChecker An UnboundedGridValidityChecker implements a strategy for determining the validity of a location in an unbounded grid.
static interface	Grid.ValidityChecker A ValidityChecker specifies a strategy for determining the validity of a location in a grid.

Field Summary

protected boolean	includeDiagonals Instance variable indicating whether the set of neighbors around each cell in the grid should include the 4 cells on the diagonals as well as the 4 cells with shared sides.
protected Grid.InternalRepresentation	internalRep Instance variable containing the internal representation of the grid, which could be implemented in a number of ways.
static int	UNBOUNDED A constant representing an unbounded (or infinite) number of rows or columns in a grid.

Constructor Summary

protected	Grid(Grid.InternalRepresentation rep) Constructs a Grid object with the specified internal representation.
protected	Grid(Grid.InternalRepresentation rep, boolean includeDiagonalNeighbors) Constructs a Grid object with the specified internal representation.

Method Summary

void	add(GridObject obj, Location loc) Adds a new object to this grid at the specified location.
GridObject[]	allObjects() Returns all the objects in this grid.
Direction	getDirection(Location fromLoc, Location toLoc) Returns the direction from one location to another.
Location	getNeighbor(Location fromLoc, Direction compassDir) Returns the adjacent neighbor (whether valid or invalid) of a location in the specified direction.
boolean	isEmpty(Location loc) Determines whether a specific location in this grid is empty.
boolean	isValid(Location loc) Verifies whether a location is valid in this grid.
java.util.ArrayList	neighborsOf(Location ofLoc) Returns the adjacent neighbors of a specified location.
int	numAdjacentNeighbors() Returns the number of adjacent neighbors around each cell.
abstract int	numCols() Returns number of columns in this grid.
int	numObjects() Returns the number of objects in this grid.
abstract int	numRows() Returns number of rows in this grid.
GridObject	objectAt(Location loc) Returns the object at a specific location in this grid.
Direction	randomDirection() Generates a random direction.
void	remove(GridObject obj) Removes the specified object from this grid.
void	remove(Location loc) Removes whatever object is at the specified location in this grid.
void	removeAll() Removes all objects from this grid.
java.lang.String	toString() Creates a single string representing all the objects in this environment (not necessarily in any particular order).

Methods inherited from class java.lang.Object

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

Field Detail

UNBOUNDED

public static final int UNBOUNDED

A constant representing an unbounded (or infinite) number of rows or columns in a grid.

See Also:

Constant Field Values

includeDiagonals

protected final boolean includeDiagonals

Instance variable indicating whether the set of neighbors around each cell in the grid should include the 4 cells on the diagonals as well as the 4 cells with shared sides.

internalRep

protected final Grid.InternalRepresentation internalRep

Instance variable containing the internal representation of the grid, which could be implemented in a number of ways.

Constructor Detail

Grid

protected Grid(Grid.InternalRepresentation rep)

Constructs a Grid object with the specified internal representation. Each cell in this grid will have at most four adjacent neighbors, the cells to its north, south, east, and west. If the grid is bounded, cells along the boundaries will have fewer than four neighbors.

Parameters:

rep - the internal representation for the grid and the objects it contains

Grid

protected Grid(Grid.InternalRepresentation rep,
               boolean includeDiagonalNeighbors)

Constructs a Grid object with the specified internal representation. Each cell in this grid will have at most four or eight adjacent neighbors, depending on the value of the includeDiagonalNeighbors parameter. If includeDiagonalNeighbors is true, each cell will have at most eight adjacent neighbors, the cells to its north, south, east, and west and the cells on the diagonals, to the northeast, southeast, northwest, and southwest. If includeDiagonalNeighbors is false, each cell will have at most the four neighbors to its north, south, east, and west. If the grid is bounded, cells along the boundaries will have fewer than the maximum four or eight neighbors.

Parameters:

rep - the internal representation for the grid and the objects it contains

Method Detail

numRows

public abstract int numRows()

Returns number of rows in this grid.

Returns:

the number of rows, or UNBOUNDED if the grid is unbounded

numCols

public abstract int numCols()

Returns number of columns in this grid.

Returns:

the number of columns, or UNBOUNDED if the grid is unbounded

isValid

public boolean isValid(Location loc)

Verifies whether a location is valid in this grid.

Parameters:

loc - location to check

Returns:

true if loc is valid; false otherwise

numAdjacentNeighbors

public int numAdjacentNeighbors()

Returns the number of adjacent neighbors around each cell.

Returns:

the number of adjacent neighbors

randomDirection

public Direction randomDirection()

Generates a random direction. The direction returned by randomDirection reflects the direction from a cell in the grid to one of its adjacent neighbors.

Returns:

a direction

getDirection

public Direction getDirection(Location fromLoc,
                              Location toLoc)

Returns the direction from one location to another. If fromLoc and toLoc are the same, getDirection arbitrarily returns Direction.NORTH.

Parameters:

fromLoc - starting location for search

toLoc - destination location

Returns:

direction from fromLoc to toLoc

getNeighbor

public Location getNeighbor(Location fromLoc,
                            Direction compassDir)

Returns the adjacent neighbor (whether valid or invalid) of a location in the specified direction.

Parameters:

fromLoc - starting location for search

compassDir - direction in which to look for adjacent neighbor

Returns:

neighbor of fromLoc in given direction (whether valid or not)

neighborsOf

public java.util.ArrayList neighborsOf(Location ofLoc)

Returns the adjacent neighbors of a specified location. Only neighbors that are valid locations in the grid will be included.

Parameters:

ofLoc - location whose neighbors to get

Returns:

a list of locations that are neighbors of ofLoc

numObjects

public int numObjects()

Returns the number of objects in this grid.

Returns:

the number of objects

allObjects

public GridObject[] allObjects()

Returns all the objects in this grid.

Returns:

an array of all the grid objects

isEmpty

public boolean isEmpty(Location loc)

Determines whether a specific location in this grid is empty.

Parameters:

loc - the location to test

Returns:

true if loc is a valid location in the context of this grid and is empty; false otherwise

objectAt

public GridObject objectAt(Location loc)

Returns the object at a specific location in this grid.

Parameters:

loc - the location in which to look

Returns:

the object at location loc; null if loc is not in the grid or is empty

toString

public java.lang.String toString()

Creates a single string representing all the objects in this environment (not necessarily in any particular order).

Overrides:

toString in class java.lang.Object

Returns:

a string indicating all the objects in this environment

add

public void add(GridObject obj,
                Location loc)

Adds a new object to this grid at the specified location. (Precondition: obj.grid() and obj.location() are both null; loc is a valid empty location in this grid.)

Parameters:

obj - the new object to be added

Throws:

java.lang.IllegalArgumentException - if the precondition is not met

remove

public void remove(GridObject obj)

Removes the specified object from this grid. (Precondition: obj is in this grid.)

Parameters:

obj - the object to be removed

Throws:

java.lang.IllegalArgumentException - if the precondition is not met

remove

public void remove(Location loc)

Removes whatever object is at the specified location in this grid. If there is no object at the specified location, this method does nothing.

Parameters:

loc - the location from which to remove an object

removeAll

public void removeAll()

Removes all objects from this grid.