beowulf.model
Class Matrix

java.lang.Object
  extended bybeowulf.model.Matrix
All Implemented Interfaces:
Collection, Serializable
Direct Known Subclasses:
IntegerMatrix, VectorMatrix

public class Matrix
extends Object
implements Collection, Serializable

This class represents a two dimensional grid of objects. Often, this is implemented using a java.util.Vector of java.util.Vector objects. This class can contain references to any object. It is not thread safe - there are no synchronized methods. This matrix can expand itself (via the right method calls), but it has no way of collapsing itself back down. In other words, it is up to the programmer to manage how the data is stored in the Matrix.

Version:
1.0 11/7/2003
Author:
Andy Scukanec (ags at cs dot cornell dot edu)
See Also:
Serialized Form

Field Summary
protected  Object[][] data
          The actual data that the matrix is holding.
protected  int numCols
          The number of columns in the matrix.
protected  int numRows
          The number of rows in the matrix.
 
Constructor Summary
Matrix()
          Creates a new 1x1 matrix.
Matrix(int size)
          Creates a new sizexsize matrix.
Matrix(int rows, int cols)
          Creates a new rowsxcols matrix.
 
Method Summary
 void add(int row, int col, Object value)
          This method performs just as put(int, int, Object) but does not fail when row or col are out of bounds.
 boolean add(Object o)
          This operation is not implemented since it does not make semantic sense to add an element to a matrix without specifying the location to which it will be added.
 boolean addAll(Collection c)
          This operation is not implemented since it does not make semantic sense to add a collection of elements to a matrix without specifying the location to which they will be added.
 void clear()
          This method sets the matrix back to a 1x1 matrix with the default value as the only entry.
 boolean contains(Object o)
          This method will return true if o is contained somewhere within the matrix.
 boolean containsAll(Collection c)
          This method takes in a java.util.Collection of elements and returns true if and only if each element of that Collection is contained in this matrix.
 void expandBy(int newAmount)
          This method expands the matrix by newAmount in each direction.
 void expandBy(int rowAmount, int colAmount)
          This method expands the matrix by the indicated amount in each direction.
 void expandTo(int newSize)
          This method ensures that this matrix is at least newSizexnewSize.
 void expandTo(int rowSize, int colSize)
          This method ensures that this matrix is at least rowSizexcolSize.
 Object get(int row, int col)
          This method returns the object at the specified position.
 int getCols()
          Returns the number of columns in this matrix.
 Object getDefaultValue()
          This method will return the default value for any given subclass of matrix.
 int getRows()
          Returns the number of rows in this matrix.
 boolean isEmpty()
          This method returns true if and only if ever element of the matrix is empty (null).
 Iterator iterator()
          This implementation of the method will return an iterator that iterates over the elements of the matrix in row major order and does not return null elements.
 void put(int row, int col, Object value)
          Sets the value at [row][col] to be value.
 void remove(int element)
          This is equivalent to calling remove(i, j) for all combinations of i and j where either is equal to element.
 void remove(int row, int column)
          Sets the element at [row][column] to be the default value.
 boolean remove(Object o)
          This method will remove an object o if it exists in this matrix.
 boolean removeAll(Collection c)
          This method will remove all of the elements of c from this matrix.
 void removeCol(int col)
          This is equivalent to calling remove(i, j) for all combinations of i and j where j is equal to col.
 void removeRow(int row)
          This is equivalent to calling remove(i, j) for all combinations of i and j where i is equal to row.
 boolean retainAll(Collection c)
          This method will iterate over all of the elements of the matrix and will keep an element in the matrix if and only if the matrix element is in c.
 int size()
          Returns the number of elements in this matrix.
 Object[] toArray()
          This will convert the entire matrix into an array.
 Object[] toArray(Object[] a)
          This method will place all of the elements of this matrix into a single array and return it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Field Detail

data

protected Object[][] data
The actual data that the matrix is holding.


numRows

protected int numRows
The number of rows in the matrix.


numCols

protected int numCols
The number of columns in the matrix.

Constructor Detail

Matrix

public Matrix()
Creates a new 1x1 matrix.


Matrix

public Matrix(int size)
Creates a new sizexsize matrix.

Parameters:
size - The size of the new matrix.

Matrix

public Matrix(int rows,
              int cols)
Creates a new rowsxcols matrix.

Parameters:
rows - The number of rows in the new matrix.
cols - The number of columns in the new matrix.
Method Detail

getRows

public int getRows()
Returns the number of rows in this matrix.

Returns:
The numer of rows in this matrix.

getCols

public int getCols()
Returns the number of columns in this matrix.

Returns:
The numer of columns in this matrix.

removeRow

public void removeRow(int row)
This is equivalent to calling remove(i, j) for all combinations of i and j where i is equal to row.

Parameters:
row - The row to zero out.

removeCol

public void removeCol(int col)
This is equivalent to calling remove(i, j) for all combinations of i and j where j is equal to col.

Parameters:
col - The column to zero out.

remove

public void remove(int element)
This is equivalent to calling remove(i, j) for all combinations of i and j where either is equal to element.

Parameters:
element - The row/column to zero out.

remove

public void remove(int row,
                   int column)
Sets the element at [row][column] to be the default value.

Parameters:
row - The row of the element to remove.
column - The column of the element to remove.

expandTo

public void expandTo(int newSize)
This method ensures that this matrix is at least newSizexnewSize. If this is smaller than the current size, the elements with the higher valued indices are dropped. If this is bigger than the current size, the new spots are filled in with the default value.

Parameters:
newSize - The minimum size of the matrix.

expandTo

public void expandTo(int rowSize,
                     int colSize)
This method ensures that this matrix is at least rowSizexcolSize. If this is smaller than the current size, the elements with the higher valued indices are dropped. If this is bigger than the current size, the new spots are filled in with the default value.

Parameters:
rowSize - The minimum number of rows in the matrix.
colSize - The minimum number of columns in the matrix.

expandBy

public void expandBy(int newAmount)
This method expands the matrix by newAmount in each direction. The new spots are set to null.

Parameters:
newAmount - The amount by which the matrix should expand.

expandBy

public void expandBy(int rowAmount,
                     int colAmount)
This method expands the matrix by the indicated amount in each direction. The new spots are filled in with the default value.

Parameters:
rowAmount - The number of new rows to add.
colAmount - The number of new columns to add.

get

public Object get(int row,
                  int col)
This method returns the object at the specified position. If either row or col are out of bounds, an exception is thrown. The return value might be null.

Parameters:
row - The row index of the value.
col - The column index of the value.
Returns:
The value at the indicated location.

put

public void put(int row,
                int col,
                Object value)
Sets the value at [row][col] to be value. If either row or col are out of bounds, and exception will be thrown.

Parameters:
row - The row index of the value to set.
col - The column index of the value to set.
value - The new value of the indicated position.

add

public void add(int row,
                int col,
                Object value)
This method performs just as put(int, int, Object) but does not fail when row or col are out of bounds. Rather, it will expand to the size implied by row and col until the indicated location exists. The value at that point will then be set.

Parameters:
row - The row index of the value to set.
col - The column index of the value to set.
value - The new value of the indicated position.

getDefaultValue

public Object getDefaultValue()
This method will return the default value for any given subclass of matrix. For the standard matrix, null is always the default value.

Returns:
null.

toArray

public Object[] toArray(Object[] a)
This method will place all of the elements of this matrix into a single array and return it. The runtime type of this array is determined by using a If the elements of this matrix will fit entirely into a, it is used. Otherwise a new array is allocated and the data are copied into this new array. If the given array is null, a NullPointerException will be thrown.

Specified by:
toArray in interface Collection
Parameters:
a - the array into which the elements of the Vector 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 the Vector.
Throws:
ArrayStoreException - the runtime type of a is not a supertype of the runtime type of every element in this Vector.
NullPointerException - if the given array is null.

toArray

public Object[] toArray()
This will convert the entire matrix into an array. The returned array will contain the elements of the matrix in row major order. null values are allowed in the returned array.

Specified by:
toArray in interface Collection
Returns:
An array representation of this matrix.

size

public int size()
Returns the number of elements in this matrix. This is equal to the number of rows multiplied by the number of columns. Note that this will include null elements.

Specified by:
size in interface Collection
Returns:
The number of elements in the matrix.

isEmpty

public boolean isEmpty()
This method returns true if and only if ever element of the matrix is empty (null).

Specified by:
isEmpty in interface Collection
Returns:
True if and only if the entire matrix is empty.

add

public boolean add(Object o)
This operation is not implemented since it does not make semantic sense to add an element to a matrix without specifying the location to which it will be added. False is always returned.

Specified by:
add in interface Collection
Parameters:
o - The object to be added.
Returns:
False.

addAll

public boolean addAll(Collection c)
This operation is not implemented since it does not make semantic sense to add a collection of elements to a matrix without specifying the location to which they will be added. False is always returned.

Specified by:
addAll in interface Collection
Parameters:
c - The collection of elements to be added.
Returns:
False.

remove

public boolean remove(Object o)
This method will remove an object o if it exists in this matrix. .equals(Object) will be used to test equality, and if such an element exists, remove(int, int) will be called to remove the element from its spot in the matrix. The return value will indicate whether or not the matrix changed as a result of this operation. Only the first occurance of o will be removed.

Specified by:
remove in interface Collection
Parameters:
o - The object to remove.
Returns:
True if and only if the matrix changed.

clear

public void clear()
This method sets the matrix back to a 1x1 matrix with the default value as the only entry.

Specified by:
clear in interface Collection

retainAll

public boolean retainAll(Collection c)
This method will iterate over all of the elements of the matrix and will keep an element in the matrix if and only if the matrix element is in c. The return value will indicate whether or not the matrix changed as a result of this operation. The element will be removed by calling remove(int i, int j) . null elements will be ignored.

Specified by:
retainAll in interface Collection
Parameters:
c - The collection of elements to keep.
Returns:
True if and only if the matrix changed.

removeAll

public boolean removeAll(Collection c)
This method will remove all of the elements of c from this matrix. This is equivalent to calling remove(Object) on each element of c. The return value will indicate whether or not the return value changed as a result of this operation. Element removal will be implemented by calling .remove(Object o) with the element to be removed as a parameter.

Specified by:
removeAll in interface Collection
Parameters:
c - The collection of elements to remove from this matrix.
Returns:
True if and only if the matrix changed at all.

contains

public boolean contains(Object o)
This method will return true if o is contained somewhere within the matrix. .equals(Object) will be used to test for equality.

Specified by:
contains in interface Collection
Parameters:
o - The object to search for in the matrix.
Returns:
True if the object is in the matrix, false otherwise.

containsAll

public boolean containsAll(Collection c)
This method takes in a java.util.Collection of elements and returns true if and only if each element of that Collection is contained in this matrix. .equals(Object o) is used to test for equality.

Specified by:
containsAll in interface Collection
Parameters:
c - The collection of elements that this method will search for in the matrix.
Returns:
True if each element of c is contained in this matrix.

iterator

public Iterator iterator()
This implementation of the method will return an iterator that iterates over the elements of the matrix in row major order and does not return null elements. The remove() operation is unsupported.

Specified by:
iterator in interface Collection
Returns:
An iterator that iterates over the matrix elements