ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.collections
Interface Matrix<E>

Type Parameters:
E - the type of the elements.
All Superinterfaces:
Collection<E>, Iterable<E>
All Known Implementing Classes:
AbstractMatrix, DenseMatrix

public interface Matrix<E>
extends Collection<E>

Represents a two-dimensional matrix of objects. Each element of a matrix can be referenced using a two-dimensional index (r, c), where r = 0,…, R - 1 is the row index, and c = 0,…, C - 1 is the column index. Methods are specified by this interface to resize matrices by adding or removing rows or columns. A class implementing this interface might implement the RandomAccess interface. This means that the get(int, int) operation is efficient, and that the returned views also implement RandomAccess.


Method Summary
 List<E> asList()
          Returns a list view of this matrix.
 int columns()
          Returns the number of columns in this matrix.
 boolean equals(Object o)
          Compares the specified object with this matrix for equality.
 E get(int r, int c)
          Returns the element at index (r, c) of the matrix.
 int hashCode()
          Returns the hash code value for the matrix.
 Iterator<E> iterator()
          Constructs and returns an iterator traversing the elements of this matrix rowise.
 int rows()
          Returns the number of rows in this matrix.
 E set(int r, int c, E value)
          Sets the element at index (r, c) of the matrix to value, and returns the element previously at that position.
 void setColumns(int numColumns)
          Sets the number of columns of this matrix to numColumns.
 void setRows(int numRows)
          Sets the number of rows of this matrix to numRows.
 Object[][] to2DArray()
          Returns a 2D array containing the elements of this matrix in the proper sequence.
 E[][] to2DArray(E[][] array)
          Returns a 2D array containing the elements of this matrix in the proper sequence; the runtime type of the returned array is the same as the runtime type of the given array.
 List<E> viewColumn(int c)
          Returns a list representing a view of column c of this matrix.
 Matrix<E> viewPart(int fromRow, int fromColumn, int toRow, int toColumn)
          Returns a view of a portion of this matrix containing rows fromRow (inclusive) to toRow (exclusive), and columns fromColumn (inclusive) to toColumn (exclusive).
 List<E> viewRow(int r)
          Returns a list representing a view of row r of this matrix.
 
Methods inherited from interface java.util.Collection
add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
 

Method Detail

rows

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

Returns:
the number of rows in this matrix.

columns

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

Returns:
the number of columns in this matrix.

setRows

void setRows(int numRows)
Sets the number of rows of this matrix to numRows. If numRows is smaller than rows(), the last rows of the matrix are removed. If numRows is greater than rows(), new rows filled with null references are added to the matrix. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
numRows - the new number of rows in the matrix.
Throws:
IllegalArgumentException - if numRows is negative.
UnsupportedOperationException - if this method is not supported.

setColumns

void setColumns(int numColumns)
Sets the number of columns of this matrix to numColumns. If numColumns is smaller than columns(), the last columns of the matrix are removed. If numColumns is greater than columns(), new columns filled with null references are added to the matrix. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
numColumns - the new number of columns in the matrix.
Throws:
IllegalArgumentException - if numColumns is negative.
UnsupportedOperationException - if this method is not supported.

get

E get(int r,
      int c)
Returns the element at index (r, c) of the matrix.

Parameters:
r - the row index.
c - the column index.
Returns:
the value of the element.
Throws:
IndexOutOfBoundsException - if r or c are negative, if r is greater than or equal to rows(), or if c is greater than or equal to columns().

set

E set(int r,
      int c,
      E value)
Sets the element at index (r, c) of the matrix to value, and returns the element previously at that position. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
r - the row index.
c - the column index.
value - the value of the element.
Returns:
the previous value of the element.
Throws:
IndexOutOfBoundsException - if r or c are negative, if r is greater than or equal to rows(), or if c is greater than or equal to columns().
UnsupportedOperationException - if this method is not implemented.

iterator

Iterator<E> iterator()
Constructs and returns an iterator traversing the elements of this matrix rowise.

Specified by:
iterator in interface Collection<E>
Specified by:
iterator in interface Iterable<E>
Returns:
the constructed iterator.

asList

List<E> asList()
Returns a list view of this matrix. Element i=rC + c of the returned list must correspond to element (r, c) of the matrix. As a result, when considering a matrix as a list and iterating over elements, elements are enumerated rowise. However, elements cannot be added or removed from the returned list, because the backing matrix must remain rectangular. One can however use List.set(int, E) to change elements. The bahavior of the returned list is undefined if the dimensions of the backing matrix are changed. This method is optional, and throws an UnsupportedOperationException if not implemented.

Returns:
the list view.
Throws:
UnsupportedOperationException - if this method is not implemented.

viewRow

List<E> viewRow(int r)
Returns a list representing a view of row r of this matrix. Any change to this matrix is reflected on the returned list while the elements of the returned list can be modified using Object). The bahavior of the returned list is undefined if the dimensions of the backing matrix are changed. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
r - the index of the row to get a view for.
Returns:
the view of the selected row.
Throws:
IndexOutOfBoundsException - if r is negative or greater than or equal to rows().
UnsupportedOperationException - if this method is not implemented.

viewColumn

List<E> viewColumn(int c)
Returns a list representing a view of column c of this matrix. Any change to this matrix is reflected on the returned list while the elements of the returned list can be modified using Object). The bahavior of the returned list is undefined if the dimensions of the backing matrix are changed. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
c - the index of the column to get a view for.
Returns:
the view of the selected column.
Throws:
IndexOutOfBoundsException - if c is negative or greater than or equal to columns().
UnsupportedOperationException - if this method is not implemented.

viewPart

Matrix<E> viewPart(int fromRow,
                   int fromColumn,
                   int toRow,
                   int toColumn)
Returns a view of a portion of this matrix containing rows fromRow (inclusive) to toRow (exclusive), and columns fromColumn (inclusive) to toColumn (exclusive). The bahavior of the returned matrix is undefined if the dimensions of the backing matrix are changed. This method is optional, and throws an UnsupportedOperationException if not implemented.

Parameters:
fromRow - the starting row.
fromColumn - the ending row.
toRow - the starting column.
toColumn - the ending column.
Returns:
the view of the matrix.
Throws:
IndexOutOfBoundsException - if row or column indices are out of bounds.
IllegalArgumentException - if fromRow is greater than toRow, or fromColumn is greater than toColumn.
UnsupportedOperationException - if this method is not implemented.

to2DArray

Object[][] to2DArray()
Returns a 2D array containing the elements of this matrix in the proper sequence.

Returns:
the array containing the elements of this matrix.

to2DArray

E[][] to2DArray(E[][] array)
Returns a 2D array containing the elements of this matrix in the proper sequence; the runtime type of the returned array is the same as the runtime type of the given array.

Parameters:
array - the array to use.
Returns:
the array containing the elements of this matrix.

equals

boolean equals(Object o)
Compares the specified object with this matrix for equality. Returns true if and only if the specified object is also a matrix, both matrices have the same dimensions, and all corresponding pairs of elements in the two matrices are equal. (Two elements e1 and e2 are equal if (e1 == null ? e2 == null : e1.equals (e2)).) In other words, two matrices are defined to be equal if they contain the same elements in the same order. This definition ensures that the equals method works properly across different implementations of the Matrix interface.

Specified by:
equals in interface Collection<E>
Overrides:
equals in class Object

hashCode

int hashCode()
Returns the hash code value for the matrix. The hash code of a matrix is defined to be 31*(31*R + C) + H, where H is the hash code of the list view returned by asList(). This ensures that matrix1.equals (matrix2) implies that matrix1.hashCode() == matrix2.hashCode() for any two matrices, matrix1 and matrix2, as required by the general contract of Object.hashCode.

Specified by:
hashCode in interface Collection<E>
Overrides:
hashCode in class Object

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.