org.jscience.mathematics.algebraic.matrices
Class BooleanMatrix

java.lang.Object
  extended by org.jscience.mathematics.algebraic.AbstractHypermatrix
      extended by org.jscience.mathematics.algebraic.AbstractMatrix
          extended by org.jscience.mathematics.algebraic.matrices.BooleanMatrix
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Algebra.Member, Ring.Member, AbelianGroup.Member, Hypermatrix, Matrix, Module.Member, VectorSpace.Member, Member

public class BooleanMatrix
extends AbstractMatrix
implements java.lang.Cloneable, java.io.Serializable

Fixed sized (non resizable) n*m boolean matrix. A boolean matrix has a number of columns and rows, which are assigned upon instance construction - The matrix's size is then columns()*rows(). booleans are accessed via (column,row) coordinates.

Individual booleans can be examined, set, or cleared. Rectangular parts (boxes) can quickly be extracted, copied and replaced. Quick iteration over boxes is provided by optimized internal iterators (forEach() methods). One BooleanMatrix may be used to modify the contents of another BooleanMatrix through logical AND, OR, XOR and other similar operations.

Legal coordinates range from [0,0] to [columns()-1,rows()-1]. Any attempt to access a boolean at a coordinate column<0 || column>=columns() || row<0 || row>=rows() will throw an IndexOutOfBoundsException. Operations involving two boolean matrices (like AND, OR, XOR, etc.) will throw an IllegalArgumentException if both boolean matrices do not have the same number of columns and rows.

If you need extremely quick access to individual booleans: Although getting and setting individual booleans with methods get(...) and put(...) is quick, it is even quicker (but not safe) to use getQuick(...) and putQuick(...).

Note that this implementation is not synchronized.

See Also:
BooleanVector, BitSet, Serialized Form

Constructor Summary
BooleanMatrix(boolean[][] array)
          Constructs a vector by wrapping an array.
BooleanMatrix(BooleanMatrix mat)
          Copy constructor.
BooleanMatrix(int rows, int columns)
          Constructs a boolean matrix with a given number of columns and rows.
 
Method Summary
 AbelianGroup.Member add(AbelianGroup.Member m)
          Returns the addition (or) of this matrix and another.
 BooleanMatrix add(BooleanMatrix m)
          Returns the addition (or) of this matrix and another.
 BooleanMatrix and(BooleanMatrix other)
          Performs a logical AND of the receiver with another boolean matrix.
 BooleanMatrix andNot(BooleanMatrix other)
          Clears all of the booleans in receiver whose corresponding boolean is set in the other boolean matrix.
 BooleanMatrix clear()
          Clears all booleans of the receiver.
 java.lang.Object clone()
          Clone matrix into a new matrix.
protected  void containsBox(int column, int row, int width, int height)
          Checks whether the receiver contains the given box.
 boolean equals(java.lang.Object obj)
          Compares this object against the specified object.
 AbstractBooleanVector getColumn(int j)
          Returns the ith column.
 Boolean getElement(int row, int column)
          Returns an element of this matrix.
 boolean getPrimitiveElement(int row, int column)
          Returns from the receiver the value of the boolean at the specified coordinate (this is the fastest way of getting an element for this kind of matrix).
 AbstractBooleanVector getRow(int i)
          Returns the ith row.
 int hashCode()
          Returns a hash code value for the NON EMPTY receiver.
 BooleanMatrix mapElements(PrimitiveMapping f)
          Applies a function on all the matrix elements.
 BooleanMatrix multiply(BooleanMatrix m)
          Returns the multiplication of this matrix and another.
 BooleanVector multiply(BooleanVector v)
          Returns the multiplication of a vector by this matrix.
 Ring.Member multiply(Ring.Member m)
          Returns the multiplication of this matrix and another.
 AbelianGroup.Member negate()
          Returns the negative (not) of this matrix.
 BooleanMatrix not()
          Performs a logical NOT on the booleans of the receiver.
 BooleanMatrix or(BooleanMatrix other)
          Performs a logical OR of the receiver with another boolean matrix.
 BooleanMatrix part(int column, int row, int width, int height)
          Constructs and returns a new matrix with width columns and height rows which is a copy of the contents of the given box.
 void replaceBoxWith(int column, int row, int width, int height, boolean value)
          Sets the booleans in the given box to the state specified by value.
 void replaceBoxWith(int column, int row, int width, int height, BooleanMatrix source, int sourceColumn, int sourceRow)
          Replaces a box of the receiver with the contents of another matrix's box.
 VectorSpace.Member scalarDivide(Field.Member x)
          Returns the division of this matrix by a scalar.
 BooleanMatrix scalarMultiply(boolean x)
          Returns the multiplication (and) of this matrix by a scalar.
 Module.Member scalarMultiply(Ring.Member x)
          Returns the multiplication (and) of this matrix by a scalar.
 void setAllElements(boolean b)
          Sets the value of all elements of the matrix.
 void setColumn(int j, AbstractBooleanVector v)
          Sets the jth column.
 void setElement(int row, int column, boolean value)
          Sets the boolean at the specified coordinate to the state specified by value.
 void setElement(int row, int column, Boolean value)
          Sets the boolean at the specified coordinate to the state specified by value.
 void setRow(int i, AbstractBooleanVector v)
          Sets the ith row.
 AbelianGroup.Member subtract(AbelianGroup.Member m)
          Returns the subtraction (or not) of this matrix by another.
 BooleanMatrix subtract(BooleanMatrix m)
          Returns the subtraction (or not) of this matrix by another.
 BooleanVector toBooleanVector()
          Converts the receiver to a booleanvector.
 ComplexMatrix toComplexMatrix()
          Converts this matrix to a complex matrix.
 DoubleMatrix toDoubleMatrix()
          Converts this matrix to a double matrix.
 IntegerMatrix toIntegerMatrix()
          Converts this matrix to a integer matrix.
 boolean[][] toPrimitiveArray()
          Projects the matrix to an array.
 java.lang.String toString()
          Returns a (very crude) string representation of the receiver.
 Matrix transpose()
          Returns the transpose of this matrix.
 int trueBooleans()
          Returns the number of booleans currently in the true state.
 BooleanMatrix xor(BooleanMatrix other)
          Performs a logical XOR of the receiver with another boolean matrix.
 
Methods inherited from class org.jscience.mathematics.algebraic.AbstractMatrix
getElement, getInvalidElementMsg, numColumns, numRows, print, print, print, print, toArray, toArray
 
Methods inherited from class org.jscience.mathematics.algebraic.AbstractHypermatrix
getDimensions, numDimensions, numElements, numElements, toArray
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.jscience.mathematics.algebraic.Hypermatrix
getDimensions, numDimensions, numElements, numElements, toArray
 

Constructor Detail

BooleanMatrix

public BooleanMatrix(int rows,
                     int columns)
Constructs a boolean matrix with a given number of columns and rows. All booleans are initially false.

Parameters:
columns - the number of columns the matrix shall have.
rows - the number of rows the matrix shall have.
Throws:
java.lang.IllegalArgumentException - if columns < 0 || rows < 0.

BooleanMatrix

public BooleanMatrix(boolean[][] array)
Constructs a vector by wrapping an array.

Parameters:
array - an assigned value

BooleanMatrix

public BooleanMatrix(BooleanMatrix mat)
Copy constructor.

Parameters:
mat - an assigned value
Method Detail

toIntegerMatrix

public IntegerMatrix toIntegerMatrix()
Converts this matrix to a integer matrix.

Returns:
a double matrix

toDoubleMatrix

public DoubleMatrix toDoubleMatrix()
Converts this matrix to a double matrix.

Returns:
a double matrix

toComplexMatrix

public ComplexMatrix toComplexMatrix()
Converts this matrix to a complex matrix.

Returns:
a complex matrix

trueBooleans

public int trueBooleans()
Returns the number of booleans currently in the true state. Optimized for speed. Particularly quick if the receiver is either sparse or dense.


getPrimitiveElement

public boolean getPrimitiveElement(int row,
                                   int column)
Returns from the receiver the value of the boolean at the specified coordinate (this is the fastest way of getting an element for this kind of matrix). The value is true if this boolean is currently set; otherwise, returns false.

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
Returns:
the value of the boolean at the specified coordinate.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column>=columns() || row<0 || row>=rows()

getElement

public Boolean getElement(int row,
                          int column)
Returns an element of this matrix.

Specified by:
getElement in interface Matrix
Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
Returns:
DOCUMENT ME!
Throws:
IllegalDimensionException - If attempting to access an invalid element.

getRow

public AbstractBooleanVector getRow(int i)
Returns the ith row.

Specified by:
getRow in interface Matrix
Parameters:
i - DOCUMENT ME!
Returns:
DOCUMENT ME!

getColumn

public AbstractBooleanVector getColumn(int j)
Returns the ith column.

Specified by:
getColumn in interface Matrix
Parameters:
j - DOCUMENT ME!
Returns:
DOCUMENT ME!

setRow

public void setRow(int i,
                   AbstractBooleanVector v)
Sets the ith row.


setColumn

public void setColumn(int j,
                      AbstractBooleanVector v)
Sets the jth column.


containsBox

protected void containsBox(int column,
                           int row,
                           int width,
                           int height)
Checks whether the receiver contains the given box.


part

public BooleanMatrix part(int column,
                          int row,
                          int width,
                          int height)
Constructs and returns a new matrix with width columns and height rows which is a copy of the contents of the given box. The box ranges from [column,row] to [column+width-1,row+height-1], all inclusive.

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
width - the width of the box.
height - the height of the box.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column+width>columns() || row<0 || row+height>rows()

setElement

public void setElement(int row,
                       int column,
                       boolean value)
Sets the boolean at the specified coordinate to the state specified by value.

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
value - the value of the boolean to be copied into the specified coordinate.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column>=columns() || row<0 || row>=rows()

setElement

public void setElement(int row,
                       int column,
                       Boolean value)
Sets the boolean at the specified coordinate to the state specified by value.

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
value - the value of the boolean to be copied into the specified coordinate.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column>=columns() || row<0 || row>=rows()

setAllElements

public void setAllElements(boolean b)
Sets the value of all elements of the matrix.

Parameters:
b - a boolean element

replaceBoxWith

public void replaceBoxWith(int column,
                           int row,
                           int width,
                           int height,
                           BooleanMatrix source,
                           int sourceColumn,
                           int sourceRow)
Replaces a box of the receiver with the contents of another matrix's box. The source box ranges from [sourceColumn,sourceRow] to [sourceColumn+width-1,sourceRow+height-1], all inclusive. The destination box ranges from [column,row] to [column+width-1,row+height-1], all inclusive. Does nothing if width <= 0 || height <= 0. If source==this and the source and destination box intersect in an ambiguous way, then replaces as if using an intermediate auxiliary copy of the receiver.

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
width - the width of the box.
height - the height of the box.
source - the source matrix to copy from(may be identical to the receiver).
sourceColumn - the index of the source column-coordinate.
sourceRow - the index of the source row-coordinate.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column+width>columns() || row<0 || row+height>rows()
java.lang.IndexOutOfBoundsException - if sourceColumn<0 || sourceColumn+width>source.columns() || sourceRow<0 || sourceRow+height>source.rows()

replaceBoxWith

public void replaceBoxWith(int column,
                           int row,
                           int width,
                           int height,
                           boolean value)
Sets the booleans in the given box to the state specified by value. The box ranges from [column,row] to [column+width-1,row+height-1], all inclusive. (Does nothing if width <= 0 || height <= 0).

Parameters:
column - the index of the column-coordinate.
row - the index of the row-coordinate.
width - the width of the box.
height - the height of the box.
value - the value of the boolean to be copied into the booleans of the specified box.
Throws:
java.lang.IndexOutOfBoundsException - if column<0 || column+width>columns() || row<0 || row+height>rows()

toBooleanVector

public BooleanVector toBooleanVector()
Converts the receiver to a booleanvector. In many cases this method only makes sense on one-dimensional matrices. WARNING: The returned booleanvector and the receiver share the same backing booleans. Modifying either of them will affect the other. If this behaviour is not what you want, you should first use copy() to make sure both objects use separate internal storage.


hashCode

public int hashCode()
Returns a hash code value for the NON EMPTY receiver.

Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Compares this object against the specified object. The result is true if and only if the argument is not null and is a BooleanMatrix object that has the same number of columns and rows as the receiver and that has exactly the same booleans set to true as the receiver.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to compare with.
Returns:
true if the objects are the same; false otherwise.

toString

public java.lang.String toString()
Returns a (very crude) string representation of the receiver.

Overrides:
toString in class java.lang.Object

clear

public BooleanMatrix clear()
Clears all booleans of the receiver.


and

public BooleanMatrix and(BooleanMatrix other)
Performs a logical AND of the receiver with another boolean matrix. The receiver is modified so that a boolean in it has the value true if and only if it already had the value true and the corresponding boolean in the other boolean matrix argument has the value true.

Parameters:
other - a boolean matrix.
Throws:
java.lang.IllegalArgumentException - if columns() != other.columns() || rows() != other.rows().

andNot

public BooleanMatrix andNot(BooleanMatrix other)
Clears all of the booleans in receiver whose corresponding boolean is set in the other boolean matrix. In other words, determines the difference (A\B) between two boolean matrices.

Parameters:
other - a boolean matrix with which to mask the receiver.
Throws:
java.lang.IllegalArgumentException - if columns() != other.columns() || rows() != other.rows().

not

public BooleanMatrix not()
Performs a logical NOT on the booleans of the receiver.


or

public BooleanMatrix or(BooleanMatrix other)
Performs a logical OR of the receiver with another boolean matrix. The receiver is modified so that a boolean in it has the value true if and only if it either already had the value true or the corresponding boolean in the other boolean matrix argument has the value true.

Parameters:
other - a boolean matrix.
Throws:
java.lang.IllegalArgumentException - if columns() != other.columns() || rows() != other.rows().

xor

public BooleanMatrix xor(BooleanMatrix other)
Performs a logical XOR of the receiver with another boolean matrix. The receiver is modified so that a boolean in it has the value true if and only if one of the following statements holds:

Parameters:
other - a boolean matrix.
Throws:
java.lang.IllegalArgumentException - if columns() != other.columns() || rows() != other.rows().

negate

public AbelianGroup.Member negate()
Returns the negative (not) of this matrix.

Specified by:
negate in interface AbelianGroup.Member
Returns:
DOCUMENT ME!

add

public AbelianGroup.Member add(AbelianGroup.Member m)
Returns the addition (or) of this matrix and another.

Specified by:
add in interface AbelianGroup.Member
Parameters:
m - a group member
Returns:
DOCUMENT ME!

add

public BooleanMatrix add(BooleanMatrix m)
Returns the addition (or) of this matrix and another.

Parameters:
m - an boolean matrix
Throws:
IllegalDimensionException - If the matrices are different sizes.

subtract

public AbelianGroup.Member subtract(AbelianGroup.Member m)
Returns the subtraction (or not) of this matrix by another.

Specified by:
subtract in interface AbelianGroup.Member
Parameters:
m - a group member
Returns:
DOCUMENT ME!

subtract

public BooleanMatrix subtract(BooleanMatrix m)
Returns the subtraction (or not) of this matrix by another.

Parameters:
m - a boolean matrix
Throws:
IllegalDimensionException - If the matrices are different sizes.

scalarMultiply

public Module.Member scalarMultiply(Ring.Member x)
Returns the multiplication (and) of this matrix by a scalar.

Specified by:
scalarMultiply in interface Module.Member
Parameters:
x - a ring member
Returns:
DOCUMENT ME!

scalarMultiply

public BooleanMatrix scalarMultiply(boolean x)
Returns the multiplication (and) of this matrix by a scalar.

Parameters:
x - an boolean
Returns:
an boolean matrix

scalarDivide

public VectorSpace.Member scalarDivide(Field.Member x)
Returns the division of this matrix by a scalar.

Specified by:
scalarDivide in interface VectorSpace.Member
Parameters:
x - a field member
Returns:
DOCUMENT ME!

multiply

public BooleanVector multiply(BooleanVector v)
Returns the multiplication of a vector by this matrix.

Parameters:
v - an integer vector
Throws:
IllegalDimensionException - If the matrix and vector are incompatible.

multiply

public Ring.Member multiply(Ring.Member m)
Returns the multiplication of this matrix and another.

Specified by:
multiply in interface Ring.Member
Parameters:
m - a ring member
Returns:
DOCUMENT ME!

multiply

public BooleanMatrix multiply(BooleanMatrix m)
Returns the multiplication of this matrix and another.

Parameters:
m - an integer matrix
Returns:
an BooleanMatrix or a IntegerSquareMatrix as appropriate
Throws:
IllegalDimensionException - If the matrices are incompatible.

transpose

public Matrix transpose()
Returns the transpose of this matrix.

Specified by:
transpose in interface Matrix
Returns:
an integer matrix

mapElements

public BooleanMatrix mapElements(PrimitiveMapping f)
Applies a function on all the matrix elements. We assume that the mapping is from int to int and that input and output values are only 0 or 1 meaning respectively false, true

Parameters:
f - a user-defined function
Returns:
a complex matrix

clone

public java.lang.Object clone()
Clone matrix into a new matrix.

Overrides:
clone in class java.lang.Object
Returns:
the cloned matrix.

toPrimitiveArray

public boolean[][] toPrimitiveArray()
Projects the matrix to an array.

Returns:
an double array.