org.jscience.mathematics.algebraic.matrices
Class BooleanMatrix

java.lang.Object
  org.jscience.mathematics.algebraic.AbstractHypermatrix
      org.jscience.mathematics.algebraic.AbstractMatrix
          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:

• The boolean initially has the value true, and the corresponding boolean in the argument has the value false.
• The boolean initially has the value false, and the corresponding boolean in the argument has the value true.

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.