it.uniroma3.mat.extendedset.wrappers.matrix

Class BinaryMatrix

java.lang.Object

it.uniroma3.mat.extendedset.wrappers.matrix.BinaryMatrix

All Implemented Interfaces:

Cloneable, Comparable<BinaryMatrix>

public class BinaryMatrix
extends Object
implements Cloneable, Comparable<BinaryMatrix>

Very similar to IntSet but for pairs of ints, that is a binary matrix

Version:

$Id$

Author:

Alessandro Colantonio

See Also:

IntSet

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BinaryMatrix.CellIterator An Iterator-like interface

Constructor Summary

Constructors

Constructor and Description
BinaryMatrix(IntSet template) Creates an empty matrix.

Method Summary

Modifier and Type	Method and Description
boolean	add(int row, int col) Adds the specified cell to this matrix if it is not already present.
boolean	addAll(BinaryMatrix other) Adds all of the cells in the specified collection to this matrix if they're not already present.
boolean	addAll(int row, IntSet cols) Adds the specified cells to this matrix, if not already present.
boolean	addAll(IntSet rowSet, int col) Adds the specified cells to this matrix, if not already present.
boolean	addAll(IntSet rowSet, IntSet colSet) Adds the specified cells to this matrix, if not already present.
double	bitmapCompressionRatio() Computes the compression factor of the equivalent bitmap representation (1 means not compressed, namely a memory footprint similar to BitSet, 2 means twice the size of BitSet, etc.)
void	clear() Removes all of the cells from this matrix.
void	clear(int fromRow, int fromCol, int toRow, int toCol) Removes from the set all the cells of the specified sub-matrix, both corners included.
BinaryMatrix	clone() See the clone() of Object
double	collectionCompressionRatio() Computes the compression factor of the equivalent integer collection (1 means not compressed, namely a memory footprint similar to ArrayList, 2 means twice the size of ArrayList, etc.)
int	compareTo(BinaryMatrix o)
void	complement() Complements the current matrix.
BinaryMatrix	complemented() Generates the complement matrix, namely flipping all the cells.
int	complementSize() Computes the complement set size.
boolean	contains(int row, int col) Returns true if this set contains the specified cell.
boolean	containsAll(BinaryMatrix other) Returns true if this matrix contains all of the cells of the specified collection.
boolean	containsAll(int row, IntSet colSet) Returns true if this matrix contains all of the cells of the specified collection.
boolean	containsAll(IntSet rowSet, int col) Returns true if this matrix contains all of the cells of the specified collection.
boolean	containsAll(IntSet rowSet, IntSet colSet) Returns true if this matrix contains all of the cells of the specified collection.
boolean	containsAny(BinaryMatrix other) Returns true if the specified BinaryMatrix instance contains any cell that is also contained within this BinaryMatrix instance
boolean	containsAtLeast(BinaryMatrix other, int minCells) Returns true if the specified BinaryMatrix instance contains at least minElements cells that are also contained within this BinaryMatrix instance
BinaryMatrix	convert(boolean[][] a) Converts a given matrix of boolean n x m into an instance of the current class.
String	debugInfo() Prints debug info about the given BinaryMatrix implementation
BinaryMatrix.CellIterator	descendingIterator()
BinaryMatrix	difference(BinaryMatrix other) Generates the difference matrix
int	differenceSize(BinaryMatrix other) Computes the difference matrix size.
BinaryMatrix	empty() Generates an empty matrix of the same dimension
IntSet	emptyRow()
boolean	equals(Object obj)
void	fill(int fromRow, int fromCol, int toRow, int toCol) Adds to the matrix all the cells of the specified sub-matrix, both corners included.
int[]	first() Returns the first (lowest) cell currently in this set.
void	flip(int row, int col) Adds the cell if it not existing, or removes it if existing
int[]	get(int i) Gets the ith cell of the matrix.
IntSet	getCol(int col) Gets a copy of the column with the given index
IntSet	getRow(int row) Gets a copy of the row with the given index
int	hashCode()
int	indexOf(int row, int col) Provides position of cell within the matrix.
BinaryMatrix	intersection(BinaryMatrix other) Generates the intersection matrix
int	intersectionSize(BinaryMatrix other) Computes the intersection matrix size.
IntSet	involvedCols()
IntSet	involvedRows()
boolean	isEmpty()
BinaryMatrix.CellIterator	iterator()
int[]	last() Returns the last (highest) cell currently in this set.
int	maxCol()
int	maxRow()
boolean	remove(int row, int col) Removes the specified cell from this matrix if it is present.
boolean	removeAll(BinaryMatrix other) Removes from this matrix all of its cells that are contained in the specified collection.
boolean	removeAll(int row, IntSet cols) Removes the specified cells from this matrix.
boolean	removeAll(IntSet rowSet, int col) Removes the specified cells from this matrix.
boolean	removeAll(IntSet rowSet, IntSet colSet) Removes the specified cells from this matrix.
boolean	retainAll(BinaryMatrix other) Retains only the cells in this matrix that are contained in the specified collection.
boolean	retainAll(int row, IntSet cols) Retains the specified cells from this matrix.
boolean	retainAll(IntSet rowSet, int col) Removes the specified cells from this matrix.
boolean	retainAll(IntSet rowSet, IntSet colSet) Removes the specified cells from this matrix.
int	size()
BinaryMatrix	symmetricDifference(BinaryMatrix other) Generates the symmetric difference matrix
int	symmetricDifferenceSize(BinaryMatrix other) Computes the symmetric difference matrix size.
boolean[][]	toArray()
boolean[][]	toArray(boolean[][] a) Returns an array containing all of the cells in this matrix.
String	toString() Generates an ASCII-art matrix representation
BinaryMatrix	transposed() Generated a transposed matrix
BinaryMatrix	union(BinaryMatrix other) Generates the union matrix
int	unionSize(BinaryMatrix other) Computes the union matrix size.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BinaryMatrix

public BinaryMatrix(IntSet template)

Creates an empty matrix. The matrix is internally represented by putting rows (transactions) in sequence. The provided constructor allows to specify which IntSet instance must be used to internally represent rows.

Parameters:

template - IntSet instance to create empty rows

Method Detail

emptyRow

public IntSet emptyRow()

Returns:

IntSet instance internally used to represent rows

intersection

public BinaryMatrix intersection(BinaryMatrix other)

Generates the intersection matrix

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the result of the operation

See Also:

retainAll(BinaryMatrix)

union

public BinaryMatrix union(BinaryMatrix other)

Generates the union matrix

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the result of the operation

See Also:

addAll(BinaryMatrix)

difference

public BinaryMatrix difference(BinaryMatrix other)

Generates the difference matrix

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the result of the operation

See Also:

removeAll(BinaryMatrix)

symmetricDifference

public BinaryMatrix symmetricDifference(BinaryMatrix other)

Generates the symmetric difference matrix

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the result of the operation

See Also:

flip(int, int)

complemented

public BinaryMatrix complemented()

Generates the complement matrix, namely flipping all the cells.

Returns:

the complement matrix

See Also:

complement()

complement

public void complement()

Complements the current matrix.

See Also:

complemented()

containsAny

public boolean containsAny(BinaryMatrix other)

Returns true if the specified BinaryMatrix instance contains any cell that is also contained within this BinaryMatrix instance

Parameters:

other - BinaryMatrix to intersect with

Returns:

a boolean indicating whether this BinaryMatrix intersects the specified BinaryMatrix.

containsAtLeast

public boolean containsAtLeast(BinaryMatrix other,
                               int minCells)

Returns true if the specified BinaryMatrix instance contains at least minElements cells that are also contained within this BinaryMatrix instance

Parameters:

other - BinaryMatrix instance to intersect with

minCells - minimum number of cells to be contained within this BinaryMatrix instance

Returns:

a boolean indicating whether this BinaryMatrix intersects the specified BinaryMatrix.

Throws:

IllegalArgumentException - if minElements < 1

intersectionSize

public int intersectionSize(BinaryMatrix other)

Computes the intersection matrix size.

This is faster than calling intersection(BinaryMatrix) and then size()

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the size

unionSize

public int unionSize(BinaryMatrix other)

Computes the union matrix size.

This is faster than calling union(BinaryMatrix) and then size()

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the size

symmetricDifferenceSize

public int symmetricDifferenceSize(BinaryMatrix other)

Computes the symmetric difference matrix size.

This is faster than calling symmetricDifference(BinaryMatrix) and then size()

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the size

differenceSize

public int differenceSize(BinaryMatrix other)

Computes the difference matrix size.

This is faster than calling difference(BinaryMatrix) and then size()

Parameters:

other - BinaryMatrix instance that represents the right operand

Returns:

the size

complementSize

public int complementSize()

Computes the complement set size.

This is faster than calling complemented() and then size()

Returns:

the size

empty

public BinaryMatrix empty()

Generates an empty matrix of the same dimension

Returns:

the empty matrix

clone

public BinaryMatrix clone()

See the clone() of Object

Overrides:

clone in class Object

Returns:

cloned object

bitmapCompressionRatio

public double bitmapCompressionRatio()

Computes the compression factor of the equivalent bitmap representation (1 means not compressed, namely a memory footprint similar to BitSet, 2 means twice the size of BitSet, etc.)

Returns:

the compression factor

collectionCompressionRatio

public double collectionCompressionRatio()

Computes the compression factor of the equivalent integer collection (1 means not compressed, namely a memory footprint similar to ArrayList, 2 means twice the size of ArrayList, etc.)

Returns:

the compression factor

iterator

public BinaryMatrix.CellIterator iterator()

Returns:

a BinaryMatrix.CellIterator instance to iterate over the matrix

descendingIterator

public BinaryMatrix.CellIterator descendingIterator()

Returns:

a BinaryMatrix.CellIterator instance to iterate over the matrix in descending order

debugInfo

public String debugInfo()

Prints debug info about the given BinaryMatrix implementation

Returns:

a string that describes the internal representation of the instance

fill

public void fill(int fromRow,
                 int fromCol,
                 int toRow,
                 int toCol)

Adds to the matrix all the cells of the specified sub-matrix, both corners included.

Parameters:

fromRow - first row of the sub-matrix

fromCol - first column of the sub-matrix

toRow - last row of the sub-matrix

toCol - last column of the sub-matrix

clear

public void clear(int fromRow,
                  int fromCol,
                  int toRow,
                  int toCol)

Removes from the set all the cells of the specified sub-matrix, both corners included.

Parameters:

fromRow - first row of the sub-matrix

fromCol - first column of the sub-matrix

toRow - last row of the sub-matrix

toCol - last column of the sub-matrix

flip

public void flip(int row,
                 int col)

Adds the cell if it not existing, or removes it if existing

Parameters:

row - row of the cell to flip

col - column of the cell to flip

See Also:

symmetricDifference(BinaryMatrix)

get

public int[] get(int i)

Gets the i^th cell of the matrix. IMPORTANT: each call returns an array of two elements, where the first element is the row, while the second element is the column of the current cell. In order to reduce the produced heap garbage, there is only one array instantiated for each BinaryMatrix instance, whose content is overridden at each method call.

Parameters:

i - position of the cell in the sorted matrix

Returns:

the i^th cell of the matrix, as a pair <row,column>

Throws:

IndexOutOfBoundsException - if i is less than zero, or greater or equal to size()

indexOf

public int indexOf(int row,
                   int col)

Provides position of cell within the matrix.

It returns -1 if the cell does not exist within the set.

Parameters:

row - row of the cell

col - column of the cell

Returns:

the cell position

convert

public BinaryMatrix convert(boolean[][] a)

Converts a given matrix of boolean n x m into an instance of the current class.

Parameters:

a - array to use to generate the new instance

Returns:

the converted collection

first

public int[] first()

Returns the first (lowest) cell currently in this set. IMPORTANT: each call returns an array of two elements, where the first element is the row, while the second element is the column of the current cell. In order to reduce the produced heap garbage, there is only one array instantiated for each BinaryMatrix instance, whose content is overridden at each method call.

Returns:

the first (lowest) cell currently in this set

Throws:

NoSuchElementException - if this set is empty

last

public int[] last()

Returns the last (highest) cell currently in this set. IMPORTANT: each call returns an array of two elements, where the first element is the row, while the second element is the column of the current cell. In order to reduce the produced heap garbage, there is only one array instantiated for each BinaryMatrix instance, whose content is overridden at each method call.

Returns:

the last (highest) cell currently in this set

Throws:

NoSuchElementException - if this set is empty

size

public int size()

Returns:

the number of cells in this matrix (its cardinality)

isEmpty

public boolean isEmpty()

Returns:

true if this matrix contains no cells

contains

public boolean contains(int row,
                        int col)

Returns true if this set contains the specified cell.

Parameters:

row - row of the cell

col - column of the cell

Returns:

true if this matrix contains the specified cell

add

public boolean add(int row,
                   int col)

Adds the specified cell to this matrix if it is not already present. It ensures that matrices never contain duplicate cells.

Parameters:

row - row of the cell

col - column of the cell

Returns:

true if this matrix did not already contain the specified cell

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

addAll

public boolean addAll(int row,
                      IntSet cols)

Adds the specified cells to this matrix, if not already present. The cells are represented by a given row and a set of columns.

Parameters:

row - index of the row

cols - indices of the columns

Returns:

true if this matrix did not already contain the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

addAll

public boolean addAll(IntSet rowSet,
                      int col)

Adds the specified cells to this matrix, if not already present. The cells are represented by a given set of rows and a given column

Parameters:

rowSet - indices of the rows

col - index of the column

Returns:

true if this matrix did not already contain the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

addAll

public boolean addAll(IntSet rowSet,
                      IntSet colSet)

Adds the specified cells to this matrix, if not already present. The cells are represented by the Cartesian product of a given set of rows and columns

Parameters:

rowSet - indices of the rows

colSet - indices of the columns

Returns:

true if this matrix did not already contain the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

remove

public boolean remove(int row,
                      int col)

Removes the specified cell from this matrix if it is present.

Parameters:

row - row of the cell

col - column of the cell

Returns:

true if this matrix contained the specified cell

Throws:

UnsupportedOperationException - if the remove operation is not supported by this matrix

removeAll

public boolean removeAll(int row,
                         IntSet cols)

Removes the specified cells from this matrix. The cells are represented by a given row and a set of columns.

Parameters:

row - index of the row

cols - indices of the columns

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being removed from this matrix

removeAll

public boolean removeAll(IntSet rowSet,
                         int col)

Removes the specified cells from this matrix. The cells are represented by a given set of rows and a given column

Parameters:

rowSet - indices of the rows

col - index of the column

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

removeAll

public boolean removeAll(IntSet rowSet,
                         IntSet colSet)

Removes the specified cells from this matrix. The cells are represented by the Cartesian product of a given set of rows and columns

Parameters:

rowSet - indices of the rows

colSet - indices of the columns

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

retainAll

public boolean retainAll(int row,
                         IntSet cols)

Retains the specified cells from this matrix. The cells are represented by a given row and a set of columns.

Parameters:

row - index of the row

cols - indices of the columns

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being removed from this matrix

retainAll

public boolean retainAll(IntSet rowSet,
                         int col)

Removes the specified cells from this matrix. The cells are represented by a given set of rows and a given column

Parameters:

rowSet - indices of the rows

col - index of the column

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

retainAll

public boolean retainAll(IntSet rowSet,
                         IntSet colSet)

Removes the specified cells from this matrix. The cells are represented by the Cartesian product of a given set of rows and columns

Parameters:

rowSet - indices of the rows

colSet - indices of the columns

Returns:

true if this matrix contains at least one of the specified cells

Throws:

IllegalArgumentException - if some property of the specified cell prevents it from being added to this matrix

containsAll

public boolean containsAll(BinaryMatrix other)

Returns true if this matrix contains all of the cells of the specified collection.

Parameters:

other - matrix to be checked for containment in this matrix

Returns:

true if this matrix contains all of the cells of the specified collection

Throws:

NullPointerException - if the specified collection contains one or more null cells and this matrix does not permit null cells (optional), or if the specified collection is null

See Also:

contains(int, int)

containsAll

public boolean containsAll(IntSet rowSet,
                           IntSet colSet)

Returns true if this matrix contains all of the cells of the specified collection.

Parameters:

rowSet - indices of the rows

colSet - indices of the columns

Returns:

true if this matrix contains all of the cells of the specified collection

containsAll

public boolean containsAll(int row,
                           IntSet colSet)

Returns true if this matrix contains all of the cells of the specified collection.

Parameters:

row - index of the row

colSet - indices of the columns

Returns:

true if this matrix contains all of the cells of the specified collection

containsAll

public boolean containsAll(IntSet rowSet,
                           int col)

Returns true if this matrix contains all of the cells of the specified collection.

Parameters:

rowSet - indices of the rows

col - index of the column

Returns:

true if this matrix contains all of the cells of the specified collection

addAll

public boolean addAll(BinaryMatrix other)

Adds all of the cells in the specified collection to this matrix if they're not already present.

Parameters:

other - matrix containing cells to be added to this matrix

Returns:

true if this matrix changed as a result of the call

Throws:

NullPointerException - if the specified collection contains one or more null cells and this matrix does not permit null cells, or if the specified collection is null

IllegalArgumentException - if some property of an cell of the specified collection prevents it from being added to this matrix

See Also:

add(int, int)

retainAll

public boolean retainAll(BinaryMatrix other)

Retains only the cells in this matrix that are contained in the specified collection. In other words, removes from this matrix all of its cells that are not contained in the specified collection.

Parameters:

other - matrix containing cells to be retained in this matrix

Returns:

true if this matrix changed as a result of the call

Throws:

NullPointerException - if this matrix contains a null cell and the specified collection does not permit null cells (optional), or if the specified collection is null

See Also:

remove(int, int)

removeAll

public boolean removeAll(BinaryMatrix other)

Removes from this matrix all of its cells that are contained in the specified collection.

Parameters:

other - matrix containing cells to be removed from this matrix

Returns:

true if this matrix changed as a result of the call

Throws:

NullPointerException - if this matrix contains a null cell and the specified collection does not permit null cells (optional), or if the specified collection is null

See Also:

remove(int, int), contains(int, int)

clear

public void clear()

Removes all of the cells from this matrix. The matrix will be empty after this call returns.

Throws:

UnsupportedOperationException - if the clear method is not supported by this matrix

toArray

public boolean[][] toArray()

Returns:

an array containing all the cells in this matrix

toArray

public boolean[][] toArray(boolean[][] a)

Returns an array containing all of the cells in this matrix.

If this matrix fits in the specified array with room to spare (i.e., the array has more cells than this matrix), the cell in the array immediately following the end of the matrix are left unchanged.

Parameters:

a - the array into which the cells of this matrix are to be stored.

Returns:

the array containing all the cells in this matrix

Throws:

NullPointerException - if the specified array is null

IllegalArgumentException - if this matrix does not fit in the specified array

compareTo

public int compareTo(BinaryMatrix o)

Specified by:

compareTo in interface Comparable<BinaryMatrix>

getRow

public IntSet getRow(int row)

Gets a copy of the row with the given index

Parameters:

row - the row index

Returns:

the content of the row

getCol

public IntSet getCol(int col)

Gets a copy of the column with the given index

Parameters:

col - the column index

Returns:

the content of the column

transposed

public BinaryMatrix transposed()

Generated a transposed matrix

Returns:

the transposed matrix

toString

public String toString()

Generates an ASCII-art matrix representation

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

maxRow

public int maxRow()

Returns:

the greatest non-empty row

maxCol

public int maxCol()

Returns:

the greatest non-empty column

involvedRows

public IntSet involvedRows()

Returns:

the index set of non-empty rows

involvedCols

public IntSet involvedCols()

Returns:

the index set of non-empty columns